diff --git a/README.md b/README.md index a8b05bc..fb6d9ea 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Landed right now: - file-backed signing-key loading/bootstrap so restart does not vaporize the service identity when you configure a real key path - signed OAuth start-state scaffolding for Discord, Patreon, GitHub, Twitch, - and YouTube + YouTube, and Spotify - durable auth/control-plane storage with in-memory and Postgres backends - account, linked-identity, session, grant, entitlement snapshot, and audit persistence @@ -33,15 +33,18 @@ Landed right now: - AES-256-GCM sealing for managed provider tokens at rest - a one-time browser completion exchange kept as fallback for opener `postMessage` handoff -- app profile surfaces for Repixelizer and StreamPixels +- app profile surfaces for Repixelizer, StreamPixels, and Spotiverse - signed claim issuance for app-local verification experiments - a local verifier helper in `src/verifier.ts` so app backends can validate Heimdall JWTs without phoning home on every guarded request +- a read-only Odin/Eve provider advertisement export that names redacted + CultCache witness document shapes and paths without touching live secrets Still not landed: - end-to-end app integrations in consumer repos - refresh/revocation flows and admin surfaces +- runtime CultCache `.cc` witness writing or CultMesh publication Canonical docs: @@ -51,6 +54,7 @@ Canonical docs: - `docs/verse-service-contract.md` - `docs/app-profiles/repixelizer.md` - `docs/app-profiles/streampixels.md` +- `docs/app-profiles/spotiverse.md` - `state/map.yaml` - `notes/fresh-workspace-handoff.md` @@ -61,6 +65,7 @@ pnpm install pnpm dev pnpm test pnpm build +pnpm export:provider-advertisement ``` ## Working Loop diff --git a/docs/service-contract.md b/docs/service-contract.md index afa3bc1..a4822a2 100644 --- a/docs/service-contract.md +++ b/docs/service-contract.md @@ -85,6 +85,7 @@ Current app slugs: - `repixelizer` - `streampixels` +- `spotiverse` Profile fields: @@ -597,6 +598,42 @@ The following are not landed yet: - revocation flows - admin/grant management surfaces - GitHub callback runtime +- runtime CultCache `.cc` witness writing or CultMesh publication + +## Odin/Eve provider advertisement + +Purpose: + +- advertise Heimdall as a read-only Eve provider surface for Odin discovery +- name the redacted CultCache witness document schemas and future `.cc` paths +- avoid touching provider secrets, token custody, store migrations, or runtime + mutation paths + +Command: + +```powershell +pnpm export:provider-advertisement +``` + +Current output shape: + +- `schemaVersion`: `gamecult.eve.provider_advertisement.v1` +- `providerId`: `heimdall` +- `status`: `read_only_witness_planned` +- provider catalog entries for Discord, Patreon, GitHub, Twitch, YouTube, and + Spotify +- app profile projections for Repixelizer, StreamPixels, and Spotiverse +- redacted witness descriptors for accounts, linked identities, grants, + sessions, entitlement snapshots, auth completions, audit events, app profiles, + and managed credential projections + +Important behavior: + +- this is a projection/export command, not a writer +- advertised witness paths are future CultCache targets, not proof that a live + `.cc` exporter is already running +- exported descriptors forbid raw provider tokens, encrypted token blobs, + completion codes, callback secrets, and app-domain state ## Next implementation move diff --git a/docs/verse-service-contract.md b/docs/verse-service-contract.md index 2f8fe65..58b37c0 100644 --- a/docs/verse-service-contract.md +++ b/docs/verse-service-contract.md @@ -99,3 +99,44 @@ refreshing an entitlement snapshot. Heimdall accepts or denies those actions. The invariant: Heimdall owns shared auth truth, not app-domain truth. CultCache and CultMesh make Heimdall inspectable; they do not leak secrets or move product state into the auth authority. + +## Read-Only Witness First Cut + +The current repo cut defines the read-only witness/ad surface without wiring a +runtime writer or migrating live state. + +Authority map: + +- Owner: Heimdall remains the only owner of auth/control-plane mutation. +- Inputs: static provider catalog, static app profiles, and the redacted witness + descriptor table in `src/verse-witness.ts`. +- Outputs: `gamecult.eve.provider_advertisement.v1` JSON printed by + `pnpm export:provider-advertisement`. +- Derived state: advertised CultCache paths and schema IDs are witness/export + targets. They do not prove that a live `.cc` writer exists yet. +- Forbidden writers: Odin probes, Eve renderers, dashboards, and this export + command cannot mutate accounts, linked identities, grants, sessions, tokens, + completions, entitlements, audit events, or app profiles. +- Shared paths: future CultCache export, CultMesh publication, and Eve lowering + should reuse the same document IDs and redaction doctrine. +- Deletion line: if a future writer needs app-domain fields or provider tokens + to make the surface useful, the design is wrong; keep those fields out or move + the concern back to the owning app/service. + +The advertised witness descriptors currently name these redacted `.cc` targets: + +- `heimdall.account.v0` at `cultcache/heimdall/accounts/{accountId}.cc` +- `heimdall.linked_identity.v0` at + `cultcache/heimdall/linked-identities/{provider}/{providerUserId}.cc` +- `heimdall.capability_grant.v0` at + `cultcache/heimdall/grants/{grantId}.cc` +- `heimdall.session.v0` at `cultcache/heimdall/sessions/{sessionId}.cc` +- `heimdall.entitlement_snapshot.v0` at + `cultcache/heimdall/entitlements/{accountId}/{provider}/{scope}.cc` +- `heimdall.auth_completion.v0` at + `cultcache/heimdall/auth-completions/{completionCodeHash}.cc` +- `heimdall.audit_event.v0` at `cultcache/heimdall/audit/{eventId}.cc` +- `heimdall.app_profile.v0` at + `cultcache/heimdall/app-profiles/{appSlug}.cc` +- `heimdall.managed_credential_projection.v0` at + `cultcache/heimdall/managed-credentials/{appSlug}/{accountId}/{provider}.cc` diff --git a/package.json b/package.json index 626b3a0..fcaf3bd 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "dev": "tsx watch src/index.ts", "start": "node dist/index.js", "test": "vitest run --config vitest.config.ts", - "typecheck": "tsc -p tsconfig.json --noEmit" + "typecheck": "tsc -p tsconfig.json --noEmit", + "export:provider-advertisement": "tsx src/export-provider-advertisement.ts --pretty" }, "dependencies": { "@fastify/cors": "^11.2.0", diff --git a/src/export-provider-advertisement.ts b/src/export-provider-advertisement.ts new file mode 100644 index 0000000..bfd0450 --- /dev/null +++ b/src/export-provider-advertisement.ts @@ -0,0 +1,23 @@ +import { buildHeimdallProviderAdvertisement } from "./verse-witness.js"; + +function readUpdatedAt(args: string[]): string { + const index = args.indexOf("--updated-at"); + const value = index >= 0 ? args[index + 1] : undefined; + + if (!value) { + return new Date().toISOString(); + } + + const parsed = new Date(value); + if (Number.isNaN(parsed.getTime())) { + throw new Error(`Invalid --updated-at value: ${value}`); + } + + return parsed.toISOString(); +} + +const pretty = process.argv.includes("--pretty"); +const updatedAt = readUpdatedAt(process.argv.slice(2)); +const advertisement = buildHeimdallProviderAdvertisement({ updatedAt }); + +process.stdout.write(`${JSON.stringify(advertisement, null, pretty ? 2 : 0)}\n`); diff --git a/src/verse-witness.ts b/src/verse-witness.ts new file mode 100644 index 0000000..32d1f87 --- /dev/null +++ b/src/verse-witness.ts @@ -0,0 +1,222 @@ +import { appProfiles, type CapabilityDefinition } from "./app-profiles.js"; +import { appSlugs, providers, type AppSlug, type Provider } from "./contracts.js"; +import { providerCatalog, type ProviderRole } from "./providers.js"; + +export const heimdallWitnessSchemaIds = [ + "heimdall.account.v0", + "heimdall.linked_identity.v0", + "heimdall.capability_grant.v0", + "heimdall.session.v0", + "heimdall.entitlement_snapshot.v0", + "heimdall.auth_completion.v0", + "heimdall.audit_event.v0", + "heimdall.app_profile.v0", + "heimdall.managed_credential_projection.v0", +] as const; + +export type HeimdallWitnessSchemaId = (typeof heimdallWitnessSchemaIds)[number]; + +export interface HeimdallWitnessDocumentDescriptor { + schemaId: HeimdallWitnessSchemaId; + documentType: HeimdallWitnessSchemaId; + cultCachePath: string; + redaction: string; + ownedTruth: string; + forbiddenFields: string[]; +} + +export const heimdallWitnessDocuments: readonly HeimdallWitnessDocumentDescriptor[] = [ + { + schemaId: "heimdall.account.v0", + documentType: "heimdall.account.v0", + cultCachePath: "cultcache/heimdall/accounts/{accountId}.cc", + redaction: "Email is optional and should be omitted unless an operator-safe identity hint is needed.", + ownedTruth: "Local GameCult account record independent of upstream providers.", + forbiddenFields: ["providerAccessToken", "providerRefreshToken"], + }, + { + schemaId: "heimdall.linked_identity.v0", + documentType: "heimdall.linked_identity.v0", + cultCachePath: "cultcache/heimdall/linked-identities/{provider}/{providerUserId}.cc", + redaction: "Token ciphertext and raw provider profile stay out; export only custody status and selected identity labels.", + ownedTruth: "External provider identity linked to exactly one Heimdall account.", + forbiddenFields: ["accessTokenEncrypted", "refreshTokenEncrypted", "profileJson"], + }, + { + schemaId: "heimdall.capability_grant.v0", + documentType: "heimdall.capability_grant.v0", + cultCachePath: "cultcache/heimdall/grants/{grantId}.cc", + redaction: "Operator notes must be reviewed before export and kept free of secrets or private app data.", + ownedTruth: "Manual or system-issued shared capability grant.", + forbiddenFields: ["providerAccessToken", "providerRefreshToken", "appDomainPayload"], + }, + { + schemaId: "heimdall.session.v0", + documentType: "heimdall.session.v0", + cultCachePath: "cultcache/heimdall/sessions/{sessionId}.cc", + redaction: "Signed tokens are never exported; claims are reduced to audience, revision, expiry, facts, and capabilities.", + ownedTruth: "Local app/browser session issued by Heimdall.", + forbiddenFields: ["accessToken", "refreshToken", "claimsJson"], + }, + { + schemaId: "heimdall.entitlement_snapshot.v0", + documentType: "heimdall.entitlement_snapshot.v0", + cultCachePath: "cultcache/heimdall/entitlements/{accountId}/{provider}/{scope}.cc", + redaction: "Raw provider responses stay out; export reason codes and compact summaries only.", + ownedTruth: "Cached provider entitlement evaluation result.", + forbiddenFields: ["rawProviderResponse", "providerAccessToken", "providerRefreshToken"], + }, + { + schemaId: "heimdall.auth_completion.v0", + documentType: "heimdall.auth_completion.v0", + cultCachePath: "cultcache/heimdall/auth-completions/{completionCodeHash}.cc", + redaction: "Completion codes are hashed or omitted; payload is redacted to status, provider, app, mode, and expiry.", + ownedTruth: "One-time OAuth browser/backend handoff completion state.", + forbiddenFields: ["code", "accessToken", "refreshToken", "callbackSecret"], + }, + { + schemaId: "heimdall.audit_event.v0", + documentType: "heimdall.audit_event.v0", + cultCachePath: "cultcache/heimdall/audit/{eventId}.cc", + redaction: "Audit payloads must pass token, code, secret, callback, and private-profile redaction before export.", + ownedTruth: "Durable auth/control-plane event history.", + forbiddenFields: ["accessToken", "refreshToken", "authorizationCode", "clientSecret"], + }, + { + schemaId: "heimdall.app_profile.v0", + documentType: "heimdall.app_profile.v0", + cultCachePath: "cultcache/heimdall/app-profiles/{appSlug}.cc", + redaction: "Profile exports contain policy shape and capability names, not app-local state.", + ownedTruth: "Per-app auth policy profile owned by Heimdall.", + forbiddenFields: ["appSharedSecret", "appDomainState"], + }, + { + schemaId: "heimdall.managed_credential_projection.v0", + documentType: "heimdall.managed_credential_projection.v0", + cultCachePath: "cultcache/heimdall/managed-credentials/{appSlug}/{accountId}/{provider}.cc", + redaction: "Expose custody status, provider subject, scopes, and expiry only; never provider tokens.", + ownedTruth: "Read-only projection that a managed provider credential exists in Heimdall custody.", + forbiddenFields: ["accessToken", "refreshToken", "accessTokenEncrypted", "refreshTokenEncrypted"], + }, +] as const; + +export interface HeimdallAdvertisedProvider { + key: Provider; + displayName: string; + roles: ProviderRole[]; + defaultScopes: string[]; + authorizationEndpoint: string; + configuredByEnv: { + clientId: string; + clientSecret: string; + }; +} + +export interface HeimdallAdvertisedAppProfile { + slug: AppSlug; + displayName: string; + profileVersion: string; + identityProviders: Provider[]; + entitlementSources: Provider[]; + managedConnectionProviders: Provider[]; + capabilities: CapabilityDefinition[]; +} + +export interface EveProviderAdvertisementDocument { + schemaVersion: "gamecult.eve.provider_advertisement.v1"; + providerId: "heimdall"; + verseId: "gamecult"; + title: "Heimdall"; + description: string; + version: string; + status: "read_only_witness_planned"; + updatedAt: string; + provider: { + id: "heimdall"; + title: "Heimdall"; + description: string; + capabilities: string[]; + usesCultMesh: boolean; + transport: string; + }; + controlSurface: { + primary: string; + controls: { + mode: "read-only"; + writes: false; + reason: string; + }; + }; + endpoints: string[]; + providers: HeimdallAdvertisedProvider[]; + appProfiles: HeimdallAdvertisedAppProfile[]; + documents: HeimdallWitnessDocumentDescriptor[]; +} + +export function buildHeimdallProviderAdvertisement(options: { updatedAt: string }): EveProviderAdvertisementDocument { + return { + schemaVersion: "gamecult.eve.provider_advertisement.v1", + providerId: "heimdall", + verseId: "gamecult", + title: "Heimdall", + description: "Shared GameCult auth/control-plane authority with redacted CultCache witness projections.", + version: "read-only-witness-v0", + status: "read_only_witness_planned", + updatedAt: options.updatedAt, + provider: { + id: "heimdall", + title: "Heimdall", + description: "Publishes provider/app auth surfaces and planned redacted witness document paths for Odin and Eve.", + capabilities: [ + "shared-auth", + "provider-oauth", + "linked-identities", + "capability-grants", + "session-claims", + "managed-credential-custody", + "redacted-cultcache-witness", + ], + usesCultMesh: true, + transport: "CultMesh provider advertisement; first cut is a read-only fixture/export.", + }, + controlSurface: { + primary: "cultmesh://gamecult/heimdall/provider-advertisement", + controls: { + mode: "read-only", + writes: false, + reason: "This export advertises witness shapes only. Runtime auth mutation remains behind Heimdall APIs.", + }, + }, + endpoints: [ + "cultmesh://gamecult/heimdall/provider-advertisement", + "cultmesh://gamecult/heimdall/witness", + ], + providers: providers.map((provider) => { + const descriptor = providerCatalog[provider]; + return { + key: descriptor.key, + displayName: descriptor.displayName, + roles: descriptor.roles, + defaultScopes: descriptor.defaultScopes, + authorizationEndpoint: descriptor.authorizationEndpoint, + configuredByEnv: { + clientId: descriptor.clientIdEnv, + clientSecret: descriptor.clientSecretEnv, + }, + }; + }), + appProfiles: appSlugs.map((appSlug) => { + const profile = appProfiles[appSlug]; + return { + slug: profile.slug, + displayName: profile.displayName, + profileVersion: profile.profileVersion, + identityProviders: profile.identityProviders, + entitlementSources: profile.entitlementSources, + managedConnectionProviders: profile.managedConnectionProviders, + capabilities: profile.capabilities, + }; + }), + documents: [...heimdallWitnessDocuments], + }; +} diff --git a/state/map.yaml b/state/map.yaml index f705898..107aba8 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -32,6 +32,7 @@ invariants: - Host apps verify signed claims locally and keep resource ownership checks local. - StreamPixels can reuse shared auth authority without centralizing streamer-audience data. - Spotiverse consumes Spotify as a Heimdall-managed credential; Spotiverse does not own Spotify refresh-token custody. + - Heimdall's first Odin/Eve provider advertisement is read-only: it names redacted CultCache witness document shapes and paths, but does not write `.cc` state or mutate auth truth. - Persistent state cruft is the same failure class as architecture cruft. data_flow: @@ -93,6 +94,7 @@ landed_baseline: - Heimdall now has generic Twitch and YouTube OAuth callback runtimes plus an app-authenticated managed-credential resolve endpoint for app-owned connector runtimes. - StreamPixels now starts viewer and creator Twitch/YouTube OAuth through Heimdall, redeems Heimdall completion codes server-side, writes its own viewer sessions and creator connector bindings, and leaves provider refresh-token custody in Heimdall. - Spotiverse now has a Heimdall app profile and Spotify provider runtime for managed credential custody. + - A read-only `gamecult.eve.provider_advertisement.v1` export now advertises Heimdall provider/app surfaces plus redacted CultCache witness document paths for Odin/Eve discovery. rejected_paths: - name: per_app_auth_copy_paste diff --git a/tests/verse-witness.test.ts b/tests/verse-witness.test.ts new file mode 100644 index 0000000..1f79a92 --- /dev/null +++ b/tests/verse-witness.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from "vitest"; +import { + buildHeimdallProviderAdvertisement, + heimdallWitnessDocuments, + heimdallWitnessSchemaIds, +} from "../src/verse-witness.js"; + +describe("Heimdall Verse witness advertisement", () => { + it("advertises the Odin/Eve provider surface and redacted witness documents", () => { + const advertisement = buildHeimdallProviderAdvertisement({ + updatedAt: "2026-06-03T12:00:00.000Z", + }); + + expect(advertisement).toMatchObject({ + schemaVersion: "gamecult.eve.provider_advertisement.v1", + providerId: "heimdall", + verseId: "gamecult", + status: "read_only_witness_planned", + updatedAt: "2026-06-03T12:00:00.000Z", + controlSurface: { + controls: { + mode: "read-only", + writes: false, + }, + }, + }); + expect(advertisement.providers.map((provider) => provider.key)).toEqual([ + "discord", + "patreon", + "github", + "twitch", + "youtube", + "spotify", + ]); + expect(advertisement.appProfiles.map((profile) => profile.slug)).toEqual([ + "repixelizer", + "streampixels", + "spotiverse", + ]); + expect(advertisement.documents.map((document) => document.schemaId)).toEqual([...heimdallWitnessSchemaIds]); + }); + + it("keeps token custody fields forbidden in witness descriptors", () => { + expect(heimdallWitnessDocuments).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + schemaId: "heimdall.linked_identity.v0", + forbiddenFields: expect.arrayContaining(["accessTokenEncrypted", "refreshTokenEncrypted"]), + }), + expect.objectContaining({ + schemaId: "heimdall.managed_credential_projection.v0", + forbiddenFields: expect.arrayContaining(["accessToken", "refreshToken"]), + }), + ]) + ); + }); +});