M7 Identity SDK

M7 Identity SDK provides integration packages for adding M7 sign-in, session handling, token validation, and live identity operations to applications and operational processes.

Choose the integration subject that matches where the identity work runs:

Subject	Use it when	Current implementation
Website integration	A browser-facing PHP application needs M7 login and a same-origin session bridge, or its backend needs to validate incoming M7 tokens.	web-php 0.1.3 and token-php 0.1.2 stable releases
CLI and background processes	A PHP command, worker, scheduler, or operational process needs to validate or acquire a token, send an authenticated resource request, or call supported live identity operations.	token-php 0.1.2 and cli-php 0.1.1 stable releases

Each section describes consumer capabilities and installation by subject. The package names identify the current implementation; they do not define the long-term documentation structure. Language-specific pages can be added below these subjects when another supported implementation is released.

M7 Identity SDK downloads

Current development-access PHP releases:

Package	Version	Downloads
Web/PHP	0.1.3	ZIP · SHA-256 · Manifest
Token/PHP	0.1.2	ZIP · SHA-256 · Manifest
CLI/PHP	0.1.1	ZIP · SHA-256 · Manifest

Verify each ZIP against its SHA-256 sidecar before extraction. The CLI requires Token/PHP 0.1.2.

Get started

• Install M7 Identity SDK for a website
• Install M7 Identity SDK for CLI and background processes

The SDK packages are distributed under MTL-10. Packagist installation is not currently available.

Package and release status

Release claims are reconciled against each package's VERSION, metadata, immutable archive, checksum, manifest, annotated release tag, tests, and current support evidence:

Package	Current status	Release boundary
web-php	0.1.3 stable artifact	The ZIP, checksum, manifest, package metadata, VERSION, and web-php-v0.1.3 tag identify the same immutable release.
token-php	0.1.2 stable artifact	The ZIP, checksum, manifest, package metadata, VERSION, and token-php-v0.1.2 tag identify the same immutable release.
cli-php	0.1.1 stable artifact	The ZIP, checksum, manifest, package metadata, VERSION, executable version, and cli-php-v0.1.1 tag identify the same immutable release. It requires token-php >=0.1.2 <0.2.0.

Current verification on 2026-09-05 confirms that all three immutable ZIPs match their SHA-256 and manifest sidecars, pass clean-extraction checks, and rebuild byte-identically. The release gates run all 10 token conformance commands, all Web/PHP conformance checks, all 111 token tests, all 55 CLI tests, PHP lint, package-autoload checks, documentation-link checks, and the forbidden-file and secret-shape policies.

Additional signing profiles in current source

The updated token-php source supports all 15 asymmetric signing profiles: RS256/384/512, PS256/384/512, ES256/384/512, ES256K, Ed25519, Ed448 and ML-DSA-44/65/87. Existing RSA and ES256/P-256 JWK verification retain PHP OpenSSL. Additional profiles, including ES256 with a PEM key, use the optional m7crypto extension and M7\Crypto\Key through the separate C library.

Use an explicit allowed_algs policy; its SDK default remains ['RS512']. Native profiles require a compatible OpenSSL provider and resolved SPKI public PEM through the existing provided-PEM or trusted x5u path. RSA-PSS also accepts the existing RSA JWK verification key. This source change does not add EC/OKP/AKP JWKS decoders or new UserInfo algorithms. Signed UserInfo remains RS256/RS512. HMAC uses the separate explicit-secret policy below; it does not add an automatic shared-secret resolver.

If a selected algorithm needs the native backend and it is absent or cannot perform the operation, verification fails explicitly. The low-level verifier throws SignatureVerificationException; the facade returns its existing unsuccessful validation report. Signature checking is never skipped. Local issuer, audience, time, scope, DPoP and trusted-key policies still apply.

The source was deployed for M7's USER/API.USER integration and Ed25519 browser login and refresh were confirmed by the operator. Native verification tests cover all 15 profiles. The download ZIPs above remain immutable prior releases; they do not include new source changes automatically. Native component SDK packaging and a coordinated new Identity SDK artifact remain pending. The currently documented crypto wrapper targets PHP 8.4+; do not infer support for every PHP version accepted by the base Identity SDK. ML-DSA needs an available provider implementation (OpenSSL 3.5+ in the tested deployment).

HMAC in current source

Current Token/PHP source verifies HS256, HS384 and HS512 using an explicit hmac_secret, allowed_algs, the m7crypto extension and M7\Crypto\Key. The immutable Token/PHP 0.1.2 ZIP does not contain this addition. The current native wrapper targets PHP 8.4+; the base SDK's lower PHP requirement does not extend the wrapper's compatibility.

After loading the current Token/PHP autoloader, supply trusted policy:

use M7\Identity\M7IdentitySDK;

// Values come from trusted server configuration, never the JWT header.
$report = (new M7IdentitySDK())->validate($accessToken, [
    'allowed_algs' => ['HS512'],
    'hmac_secret' => $originalClientSecret,
    'issuer' => 'https://sso.user.m7.org',
    'audience' => 'https://api.example.com',
    'client_id' => $expectedClientId,
]);

The default allowlist remains ['RS512']. Set the expected HS algorithm explicitly. Minimum original-secret lengths are 32 bytes for HS256, 48 for HS384 and 64 for HS512; the verifier accepts at most 4096 bytes. Pass original bytes without hashing, trimming or base64-decoding. Select the client and secret from trusted configuration, not solely from unverified token claims. hmac_secret is separate from OAuth request authentication's auth.client_secret; acquiring or refreshing a token does not automatically run local MAC verification.

Missing native support, missing/short secrets, disallowed algorithms, wrong secrets and altered signatures fail closed. The facade returns an unsuccessful validation report; low-level verification errors throw. HMAC never falls back to a certificate. Secrets are not fetched through JWKS, PEM or x5u; HMAC headers containing x5u, jku, jwk or k are rejected. Keep time, issuer, audience, scope, principal and sender-constraint policies, including request-bound DPoP when required. ID tokens need the relying-party client-ID audience and transaction nonce and are not API access credentials. Treat refresh tokens as opaque client state.

A secret holder can both verify and create MACs. Local verification alone therefore does not prove provider issuance or active state. Resource servers must retain authoritative issued-token/state checks, such as applicable SSO introspection, and their resource authorization policy. Auth method none does not gain confidential introspection access by storing an HMAC secret. Public clients must use asymmetric ID-token signing. The User.M7/SSO update blocks none with HS256/384/512; it is implemented and locally tested, with production deployment verification pending. SDK MAC verification remains available, but cannot make an ineligible SSO client configuration valid.

The Web/PHP session bridge uses authenticated SSO introspection. Its HMAC browser login, profile and refresh path does not require m7crypto. Keep the OAuth client secret on the PHP server, never in browser JavaScript, URLs or session cookies. The same original secret serves HMAC and secret-based client authentication when both apply. First save confidential-client authentication for a client that can protect its credentials, then save the HMAC algorithm and set/reset its secret. Existing password hashes cannot be recovered. Retain an old secret while accepting tokens issued with it. See SSO HMAC setup.

The September 2026 current-source campaign passed HS256/384/512 browser sign-in, profile and strict refresh with PAR, authorization code, PKCE and browser DPoP. All three also passed server client-credentials and consumer device/strict-refresh campaigns. The HS256 device case used none; it remains historical signing evidence and is excluded by the eligibility policy above. Browser acceptance used a confidential PHP backend, not a JavaScript client holding a secret. The separate native Token/PHP check verified live HS512 access/refresh JWTs and rejected wrong-secret, disallowed-algorithm and tampered-signature cases. The full native Token SDK suite passed 139 tests with 1133 assertions. These results do not imply a new immutable package release, every live auth/rotation combination, or formal OpenID conformance. UserInfo's RS256/RS512 contract remains unchanged.

Post-quantum use and the Web SDK

The tested device-code pickup/refresh and machine-token flows can use ML-DSA with a compatible native verifier and suitably sized storage and transports. Device approval happens in a browser, but the relying client's token package is returned to the device process as JSON.

The current Web/PHP integration stores complete access and refresh JWTs in single cookies. Do not select ML-DSA for this browser session path yet. ML-DSA-65/87 encoded signatures alone exceed Chromium's 4,096-byte cookie name-plus-value limit; ML-DSA-44 can exceed it once the JWT header and claims are included. The native verifier working does not prove cookie acceptance. Total Cookie/Authorization headers and proxy/storage limits also matter. See the Chromium cookie-size contract.

Server-held tokens with an opaque browser session reference are a proposed follow-up, not current SDK behavior. Ed25519 provides the accepted compact browser test profile. Retain the existing published-release capabilities until updated source or a verified new artifact is installed.

Current boundaries

The website package supplies a PHP backend-for-frontend integration for browser authorization and sessions. The token package supplies a PHP library for local validation, confidential-client token acquisition, online introspection, and UserInfo operations. It also supplies public/confidential device authorization, one-attempt token pickup, complete refresh-package exchange and acknowledgement, and schema-neutral authenticated resource requests.

The separate cli-php package is the dedicated m7-identity executable adapter over token-php. Its supported command families are app, profile, password, token, client-credentials, device-code, exchange, ack, ensure, and authenticated resource request. The adapter owns terminal prompting, device polling, command output and exit status, and protected keychain persistence. The storage-neutral token library owns the protocol operations and returns reports and complete bundles without choosing CLI input, output, or storage. The CLI release verifier exercises the packaged command against the immutable token-php 0.1.2 dependency.

Neither layer currently supplies authorization-code acquisition or outbound DPoP proof generation. Callers of DPoP-bound operations must provide a fresh externally generated proof for each applicable request.

Security

Use HTTPS, verify release checksums before installation, and keep access tokens, refresh credentials, client secrets, DPoP proofs, session cookies, and deployment keys out of source control, URLs, command histories, logs, and public documentation.

Report private security issues to security@m7.org. Commercial licensing inquiries may be sent to legal@m7.org.