@juangcarmona/lighthouse 0.11.2 → 0.11.4

package/README.md

@@ -78,3 +78,7 @@ A new deterministic checker mechanism or a new engineering practice is outside t
 ## Optional GitHub repository profile
 
 The recommended `github-profile` capability is opt-in. Adopters declare checks, contribution policy and reasoned exceptions in `.lighthouse/github.json`, then use `lighthouse capabilities plan`, `apply` and `verify --id github-profile` to reconcile live settings. No remote settings change during installation or ordinary upgrades. See the [GitHub profile guide](github-profile.md) for configuration, supported controls, authorization and limitations.
+
+## External user identity
+
+Applications that need sign-in follow the [external identity contract](assets/profiles/identity.md). Reuse a shared OIDC provider; Keycloak is the self-hosted reference. The package ships guidance for application integration and acceptance evidence, while the operator owns provider deployment. Existing adopters receive the guidance through a reviewed harness upgrade.

package/assets/profiles/dotnet/SKILL.md

@@ -16,3 +16,5 @@ Use red-green development: start with unit tests, then add integration, function
 Run `npm run verify` and `npm run verify:dotnet` after a focused change. Treat unavailable evidence as a repair action, not as proof of compliance.
 
 Application code, tests and build policy become adopter-owned after creation. Do not overwrite them from the profile.
+
+Before implementing user authentication, read `assets/profiles/identity.md` in the installed Lighthouse package. Consume an external OIDC provider through maintained middleware. Keep application permissions in the product and record any custom identity-server exception explicitly.

package/assets/profiles/identity.md

@@ -0,0 +1,34 @@
+# External user identity
+
+For products that need user authentication, use an external OpenID Connect (OIDC) provider and maintained framework middleware. Public applications need not add authentication. Keycloak is the recommended self-hosted reference; an existing standards-compatible provider is equally valid. Lighthouse defines this integration guidance and does not provision identity infrastructure.
+
+## Ownership and deployment
+
+Reuse a shared identity service when available. If none exists, the operator may deploy Keycloak independently of the application. Application removal must not delete the shared service, realm, accounts or database. Disposable development providers must be isolated from real users.
+
+Register separate clients for applications and client types, with environment-specific registrations, exact redirect and post-logout URLs, minimal scopes and appropriate API audiences. Choose realms by identity and administrative boundaries, not by repository count. Do not use the Keycloak master realm for application users.
+
+The operator owns TLS, a stable issuer address reachable by browsers and backends, persistent storage, tested backups, updates, restricted administration and emergency access independent of the identity service. Production deployment must not use development mode. Provider outages must not create an authentication bypass; document what happens to existing sessions and cached token validation.
+
+## Application contract
+
+- Delegate sign-in, passwords, recovery, MFA and social identity federation to the provider. A custom credential store or authorization server requires a recorded product and architecture exception with owner, reason and security evidence.
+- Use Authorization Code with PKCE for interactive sign-in. Web BFFs keep tokens on the server and expose protected session cookies. Native clients use the system browser, secure token storage and no embedded client secret.
+- APIs validate access-token signature, issuer, audience and expiry through maintained middleware; an ID token is not an API access token. Reject missing credentials and insufficient permissions without fallback identities.
+- Map identities using issuer and subject, not email alone. Keep domain membership, resource access and tenant isolation in the application. Provider roles may supply coarse permissions but do not replace resource authorization.
+- Treat access to external services as a separate authorization grant. An OIDC login does not grant repository access or permission to act as that user in another service.
+- Implement local logout and document provider logout, revocation and session expiry separately. Signing out of one application must not silently promise immediate invalidation of every token or every other application session.
+
+Keep issuer, client ID, audience, scopes, callback URLs and secret references in the application's existing configuration mechanism. Store secrets outside source control. Do not add a second identity configuration schema in Lighthouse. Changing providers may change issuer and subject identifiers; plan account linking and migration explicitly.
+
+## Acceptance evidence
+
+Before declaring the authenticated slice complete, demonstrate sign-in and callback validation, session expiry, logout and user switching against a real test provider. Test rejected callback state/nonce, wrong issuer/audience, expired tokens, missing credentials, insufficient permissions and access to another user's resources. Exercise CSRF protection for cookie-authenticated mutations. Verify that disabling an account has the documented session effect.
+
+Use isolated test accounts and sanitized evidence. Test-only identity overrides must never be enabled in the deployed application. Record provider/version, non-secret configuration, tested behavior and unresolved gaps in the application's existing acceptance evidence; do not copy tokens or credentials into logs or screenshots.
+
+These are semantic and integration requirements. Lighthouse's foundation verifier checks managed-file drift, not provider availability or security correctness. Each adopter supplies runtime tests and reviews; unavailable evidence remains a gap.
+
+## Provider references
+
+Use the [Keycloak administration guide](https://www.keycloak.org/docs/latest/server_admin/) for realms, clients and identity federation, and the [production configuration guide](https://www.keycloak.org/server/configuration-production) for operating the service. Provider deployment details remain operator-owned.

package/assets/profiles/mobile-expo/SKILL.md

@@ -12,3 +12,5 @@ Keep features aligned with product capabilities and use TanStack Query for serve
 Treat Android and iOS behavior as native evidence. Add web export only when the product selects it and keep that evidence separate.
 
 Run Expo doctor, typecheck, tests and the selected emulator or device journey after a focused change.
+
+Before implementing user authentication, read `assets/profiles/identity.md` in the installed Lighthouse package. Consume an external OIDC provider through maintained middleware. Keep application permissions in the product and record any custom identity-server exception explicitly.

package/assets/profiles/mobile-maui/SKILL.md

@@ -12,3 +12,5 @@ Keep platform capabilities behind explicit adapters and preserve the boundary be
 Use secure storage, OIDC Authorization Code with PKCE, declared permissions and tested deep links. Keep browser cookies and web routing outside the native client.
 
 Run locked restore, analyzers, unit tests and the selected emulator or device journey after a focused change.
+
+Before implementing user authentication, read `assets/profiles/identity.md` in the installed Lighthouse package. Consume an external OIDC provider through maintained middleware. Keep application permissions in the product and record any custom identity-server exception explicitly.

package/assets/profiles/web-bff/SKILL.md

@@ -14,3 +14,5 @@ Validate origin and CSRF state, allow only declared destinations and routes, and
 Implement logout, revocation, expiry and user switching as tested behavior. Keep rate limiting and observability at the BFF boundary.
 
 Run the session, API, browser and security checks after a focused change. Treat a missing security check as a repair action.
+
+Before implementing user authentication, read `assets/profiles/identity.md` in the installed Lighthouse package. Consume an external OIDC provider through maintained middleware. Keep application permissions in the product and record any custom identity-server exception explicitly.

package/assets/profiles/web-bff/security.md

@@ -3,7 +3,7 @@
 | Boundary | Contract | Required evidence |
 | --- | --- | --- |
 | Browser session | Secure, HttpOnly cookie with explicit SameSite policy | Cookie inspection and browser session test |
-| Authorization | Authorization Code with PKCE | Provider configuration and callback test |
+| Sign-in protocol | Authorization Code with PKCE | Provider configuration and callback test |
 | CSRF | Origin and request-token policy for state-changing requests | Negative and positive mutation tests |
 | Destinations | Explicit allowlist for outbound targets and routes | Rejected destination test |
 | Proxying | Fixed routes and typed upstream calls | No arbitrary proxy path |
@@ -14,3 +14,5 @@
 Do not place access or refresh tokens in localStorage, sessionStorage or IndexedDB.
 
 The BFF may be hosted inside the ASP.NET Core application host. A separate service requires a product and architecture decision with its own deployment evidence.
+
+Use an external OIDC provider with a dedicated application client. A shared provider remains operator-owned. Domain authorization and external-service grants remain separate from the browser login. Read the installed Lighthouse package's `assets/profiles/identity.md` for the shared identity contract.

package/assets/profiles/web-bff/testing.md

@@ -12,3 +12,5 @@ Test the session boundary before the browser journey: callback, cookie flags, CS
 The first vertical slice must fail closed when the session is absent, expired or assigned to another user.
 
 Keep provider credentials out of fixtures. Use a deterministic identity or approved test provider that exercises the same cookie and callback boundaries.
+
+Prove callback state and nonce rejection, resource authorization across two users, and the documented behavior during provider outages. Test fixtures alone do not prove integration with the configured OIDC provider; retain a real test-provider sign-in and logout journey before acceptance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -23,7 +23,7 @@
     "@arcshape/cli": "0.1.6",
     "@juangcarmona/lighthouse-ui": "0.2.0",
     "@prodshape/cli": "0.23.0",
-    "@juangcarmona/lighthouse-sdlc": "0.13.0"
+    "@juangcarmona/lighthouse-sdlc": "0.15.0"
   },
   "files": [
     "src/lighthouse.mjs",

package/src/lighthouse.mjs

@@ -290,7 +290,7 @@ function render(manifest) {
   const sdlcLine = selectedSdlc ? `- SDLC package: \`${selectedSdlc.name}@${selectedSdlc.version}\`\n` : '';
   const selectedUi = manifest.packages?.ui;
   const uiLine = selectedUi ? `- UI package: \`${selectedUi.name}@${selectedUi.version}\`\n` : '';
-  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n${sdlcLine}${uiLine}- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Public site: \`${publicSite}\`\n- Repository roots: ${repository.layout.map((x) => `\`${x}/\``).join(', ')}\n- Commit convention: \`${repository.conventions.commits}\`\n\n## Delivery contract\n\n${authorities} Lighthouse installs the repository baseline and verifies the selected integrations.\n\nThe repository keeps source code in \`src/\`, documentation in \`docs/\`, infrastructure in \`infra/\` and repository automation in \`scripts/\`. A project may record a narrow, owned exception, but an initializer never overwrites an existing project file.\n\nThe selected SDLC package owns lifecycle skills, commands, meta-commands, routes and gates. The \`.lighthouse/\` control plane records the selected package, command aliases and host adapters without storing agent runtime data. Use \`lighthouse aliases --format json\` or \`.lighthouse/commands.json\` to discover canonical and short agent commands.\n\n${publicSiteContract} This route publishes product and architecture documentation. Application deployment follows the repository's own delivery policy.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
+  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n${sdlcLine}${uiLine}- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Public site: \`${publicSite}\`\n- Repository roots: ${repository.layout.map((x) => `\`${x}/\``).join(', ')}\n- Commit convention: \`${repository.conventions.commits}\`\n\n## Delivery contract\n\n${authorities} Lighthouse installs the repository baseline and verifies the selected integrations.\n\nThe repository keeps source code in \`src/\`, documentation in \`docs/\`, infrastructure in \`infra/\` and repository automation in \`scripts/\`. A project may record a narrow, owned exception, but an initializer never overwrites an existing project file.\n\nThe selected SDLC package owns lifecycle skills, commands, meta-commands, routes and gates. The \`.lighthouse/\` control plane records the selected package, command aliases and host adapters without storing agent runtime data. Use \`lighthouse aliases --format json\` or \`.lighthouse/commands.json\` to discover canonical and short agent commands.\n\n${publicSiteContract} This route publishes product and architecture documentation. Application deployment follows the repository's own delivery policy.\n\n## User identity\n\nWhen the product needs user authentication, delegate it to an external OpenID Connect provider through maintained framework middleware. Reuse an existing shared provider; Keycloak is the recommended self-hosted reference. Do not build password storage, credential recovery or an authorization server without an explicit product and architecture exception. Application authorization stays in the product. Use separate application clients and keep shared identity infrastructure outside application teardown.\n\nRead the installed Lighthouse package guide at \`assets/profiles/identity.md\` before implementing authentication. This is review guidance; foundation verification does not prove runtime authentication or authorization.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
 }
 
 function guardrailScript(manifest) {