Download the PHP package phpdot/webauthn without Composer

phpdot/webauthn

This is an experimental package. The API surface may change in any release without a deprecation cycle — pin the constraint and read the release notes before upgrading.

WebAuthn and passkeys for the PHPdot ecosystem — a production wrap of web-auth/webauthn-lib: ceremony orchestration, single-use TTL-bound challenges, duplicate-credential refusal, counter discipline after every authentication, and an exception fence no vendor type leaks past. Storage is the host's, through three small contracts; authentication plugs into phpdot/iam as one stage.

Table of Contents

• Requirements
• Installation
• Usage
• Storage contract
• Architecture
• Testing
• License

Requirements

phpdot/iam (dev-only suggestion) enables the WebauthnStage bridge; phpdot/container for the binding attributes.

Installation

Usage

Strings in, strings out. Begin a ceremony and hand the JSON to the browser; take the browser's credential JSON back and finish:

beginAuthentication(null) starts a discoverable (passkey, usernameless) ceremony. The core speaks users and handles, never identities — mapping a handle to your actor is the caller's one line.

As an iam factor, that line is the bridge: WebauthnStage + your WebauthnIdentityProviderInterface mapping — passkeys work as the identifying factor or as a step-up after a password:

Configuration arrives through the #[Config('webauthn')] DTO — rpId, rpName, allowedOrigins (mandatory: an empty origin list refuses to construct rather than fall back to the library's looser deprecated origin check), the COSE algorithm set (shipped wide: ES256/384/512, RS256/384/512, PS256/384/512, Ed25519), challenge bytes (minimum 16, default 32), and the ceremony TTL (default 300s on the injected PSR-20 clock).

Storage contract

The package owns the ceremonies; the host owns storage, through two contracts plus the handle mapping.

• CredentialRecordRepositoryInterface — records travel as JSON strings (the package serializes CredentialRecord itself; the host's burden is a JSON column). Terms: credential ids are unique across all users; a record is saved after every authentication — the signature counter is the clone detector, and an unsaved record silently disarms it; payloads are opaque to the host.
• Handles, not identities — the core never knows an identity type. The user handle is the host's to mint and keep: stable, opaque, at most 64 raw bytes, never recycled across accounts — it is what binds a credential to a user across both ceremonies. With iam, the bridge's WebauthnIdentityProviderInterface maps handles to identities.
• CeremonyStoreInterface — per-ceremony state keyed by challenge, readable exactly once. Single-use is the replay protection (the library only compares challenges) and the TTL bounds what hangs. Default: SessionCeremonyStore, namespaced session keys.

Architecture

WebauthnEngine (singleton) builds the library once — serializer, wide attestation support (none and packed: real passkey clients ignore a none preference, a spec SHOULD, and would otherwise hard-fail at parse time), the wide algorithm manager, and both validators; nothing is touched after build. WebauthnService (scoped) orchestrates: challenge generation, single-use state, the duplicate refusal the library never performs, the mandatory counter write, and the exception fence — the library's two disjoint exception roots plus foreign CBOR/cose escapes all translate to PHPdot\WebAuthn\Exception\WebauthnException and its leaves.

Testing

License

MIT.

This repository is a read-only mirror, generated by CI from phpdot/monorepo. Pull requests and issues belong in the monorepo.