Built For Cloud Laravel Package

Product Decisions This Supports

• Shipping "sign in from the CLI/installer" as a feature. This package provides the protocol surface — start, human approval, single exchange, credential issuance — for authenticating a first-party CLI, desktop installer, local agent, or on-prem bootstrap tool to your Laravel app. That unblocks roadmap items currently blocked on "we have no way for a machine to authenticate a human."
• One roadmap decision, two client shapes. Device-code (approve in a browser on a second device — headless servers, SSH, CI) and exact-loopback + PKCE (desktop installers, local dev tooling) land together. The profile and purpose policy layer makes "which flow does this client get, for what purpose" an explicit product/policy call rather than an implicit one per client.
• Build vs. buy for auth. This is the build side, but a deliberately narrow build: it covers your own first-party clients without paying for or operating a full IdP. The comparison set is: buy an IdP (WorkOS/Auth0/Keycloak), adopt Passport, or build on this package. That's a decision worth making explicitly rather than defaulting to "buy enterprise" for one CLI.
• Security posture you can put in writing. Hash-only start, reveal-once credentials, browser-bound decision, serialized single exchange, cadence and expiry, connection-wide denial. That supports answering enterprise security questionnaires with "credential theft from our database is not sufficient to impersonate a device" — a sales-enablement artifact, not just an engineering one.
• Operational cost and support load planning. Approval views, prune command, and published HTTP contract docs materially reduce the "who builds the consent screen and the cleanup job" work item, and the prune command gives you a data-retention story.
• Incident response and offboarding commitments. Kind- or profile-withdrawal as a terminal denial, plus connection-wide denial, is a defensible kill-switch narrative for enterprise offboarding and revocation SLAs.

When to Consider This Package

Consider it when:

• Your Laravel app is the authorization server of record for your own first-party clients (CLI, installer, desktop app, local agent) — not a provider for third-party developers.
• You need RFC 8628-shaped device authorization and/or RFC 8252 loopback + PKCE, and the alternative is hand-rolling token endpoints and an approval UI.
• You can accept a short human-in-the-loop step, and your clients can open a URL or poll a token endpoint.
• You want the approval views, route contract, and test clients included rather than designed from scratch.
• You can pin a pre-1.0 dependency and staff an upgrade budget.

Look elsewhere when:

• You need a general OAuth 2.1 / OIDC provider for third parties — scopes, consent screens, dynamic client registration, discovery, refresh tokens. Use Passport or a dedicated IdP.
• You need SSO/SAML/SCIM, MFA policy, or compliance certifications (SOC 2, HIPAA BAA). Buy.
• You need human browser login — passwordless, magic link, social. Wrong tool.
• Your clients are SPAs or native mobile apps using the system browser with universal links / claimed HTTPS. Loopback is the wrong redirect for those.
• You cannot tolerate breaking changes across minor versions, or no one on the team can review auth code.
• Your threat model requires database-enforced invariants and an audited state machine — see the disclosed gaps below.

Adoption caveats (treat as integration requirements, not drop-in):

• The denial-reason closed vocabulary is not database-enforced. Do not build product logic, analytics, or support tooling that assumes the set of denial reasons is closed.
• DeviceAuthorizationStart carries an internal id and a reveal-once nonce that consumers must not serialize. This is an API footgun: add a serialization guard and a test before it reaches a JSON response, a log line, or an exception trace.
• The /bfc/* routes and payload shapes should be treated as unstable until 1.0.

How to Pitch It (Stakeholders)

For executives. One package gets us "sign in from our CLI/installer" without buying an IdP or funding a quarter of auth engineering. It covers both realistic client shapes — approve-in-browser for headless machines, loopback + PKCE for desktop installers — and ships the approval UI, routes, and contract docs, so the remaining schedule risk is integration, not invention. The security story is concrete and checkable: only hashes stored, credentials revealed once, a single exchange per authorization, browser-bound approval, and a per-connection kill switch. It is pre-1.0 (v0.15.0), so I recommend a scoped pilot behind one client, version-pinned, with a named upgrade owner — not a platform-wide commitment yet.

For engineering. v0.15.0 lands the full lifecycle (PR #138) plus the HTTP surface and clients (PR #140): POST /bfc/device-authorizations, GET|POST /bfc/device, POST /bfc/device/token, GET|POST /bfc/loopback/authorize, POST /bfc/loopback/token, approval views, scripted clients, the prune command, and HTTP contract docs. The invariants you would otherwise have to write and defend are already implemented: profile and purpose policy, hash-only start, browser-bound decision, serialized single exchange, cadence and expiry, containment and connection-wide denial, and exact-bound bearer use where the credential's bound subject must equal the host's resolved request subject, with kind or profile withdrawal as a terminal denial. Two disclosed gaps to design around before we merge anything: denial reasons are not DB-enforced (don't encode the vocabulary as a closed set), and DeviceAuthorizationStart must never be serialized because of its internal id and reveal-once nonce — put a guard and a regression test on that boundary first. Plan for breaking changes on the /bfc surface ahead of 1.0.