diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index a7755371..7bfe9d02 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -373,7 +373,7 @@ }, "consumerIdentityField": "logicalName", "consumerDirectories": ["src", "tests"], - "orphanExemptRows": ["QUERY_PERSISTENCE", "AUTH_TOKEN"], + "orphanExemptRows": ["QUERY_PERSISTENCE", "AUTH_TOKEN", "AUTH_REDIRECT_TRANSACTION"], "breakingFields": [ "logicalName", "physicalKey", diff --git a/docs/manual/04-paired-backend-session.md b/docs/manual/04-paired-backend-session.md index c9a6c965..d5941996 100644 --- a/docs/manual/04-paired-backend-session.md +++ b/docs/manual/04-paired-backend-session.md @@ -44,6 +44,7 @@ - `fetcher`는 마감이 없다. owner에서 쓰지 않는다. 응답하지 않는 호출 하나가 세션을 "복구 중"에 영원히 둔다. - `page`: 지금 URL, URL 바꾸기, 다른 페이지로 이동. 로그인 리다이렉트에 쓴다. - `redirectStorage`: 페이지의 sessionStorage. 리다이렉트 한 번 동안의 상태만 둔다. 토큰은 두지 않는다(`AUTH_TOKEN`은 `src/contracts/storage-keys.ts`에서 `forbidden`이다). + - 키는 registry의 `AUTH_REDIRECT_TRANSACTION`(`backend: "external"`)에서 가져온다. 그래야 `APP_NAMESPACE`를 바꿀 때 같이 바뀐다. 새 owner도 키를 글자로 적지 않는다. - `readCookie`: 페이지 쿠키 읽기. 4. recipe는 `src/bootstrap/` 아래로 **복사**한다. import하지 않는다. - `src`가 `recipes/`를 import하면 `check:optional-recipes`가 `PRODUCTION_IMPORTS_RECIPE`로 막는다. diff --git a/recipes/session-owners/oidc-pkce-session-owner.ts b/recipes/session-owners/oidc-pkce-session-owner.ts index 72301076..07a04b4c 100644 --- a/recipes/session-owners/oidc-pkce-session-owner.ts +++ b/recipes/session-owners/oidc-pkce-session-owner.ts @@ -8,6 +8,7 @@ import type { ProductSessionOwnerPage, SessionOwnerFetch, } from "../../src/bootstrap/product-composition-contract.ts"; +import { STORAGE_REGISTRY } from "../../src/contracts/storage-keys.ts"; /** * 1103/09-03. A session owner for the paired backend's JWT mode @@ -40,8 +41,15 @@ import type { * shows the realm client and the wiring. */ -/** `buildPhysicalKey("auth", 1, "oidc-pkce-transaction")`; never a token. */ -export const OIDC_PKCE_TRANSACTION_KEY = "ca-frontend:auth:v1:oidc-pkce-transaction"; +/** + * The sessionStorage key of the sign-in transaction; never a token. + * 1105/05-01. It comes from the storage registry + * (`AUTH_REDIRECT_TRANSACTION`, `backend: "external"`), so it follows the + * app's `APP_NAMESPACE` like every other Web Storage key. It used to be a + * literal that kept `ca-frontend:` after a product renamed the namespace. + */ +export const OIDC_PKCE_TRANSACTION_KEY = + STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION.physicalKey; export type OidcPkceSessionOwnerOptions = Readonly<{ /** Exact issuer, e.g. `http://localhost:8081/realms/ca-skeleton`. HTTPS off this machine. */ diff --git a/src/contracts/storage-keys.ts b/src/contracts/storage-keys.ts index 38f99821..b58c144d 100644 --- a/src/contracts/storage-keys.ts +++ b/src/contracts/storage-keys.ts @@ -133,6 +133,28 @@ export const STORAGE_REGISTRY = Object.freeze({ migration: "discard", quotaFallback: "feature-disable", }), + /** + * 1105/05-01. The OIDC PKCE session owner recipe + * (`recipes/session-owners/oidc-pkce-session-owner.ts`) keeps one sign-in + * transaction here in sessionStorage: the PKCE verifier, `state`, `nonce` + * and the return path, never a token, for at most ten minutes, and the + * callback deletes it first. The recipe owns the value format, so only the + * name lives here and StoragePort refuses the key. It is not + * `sensitive-forbidden`, which means "never stored"; this one is stored by + * design for one redirect. + */ + AUTH_REDIRECT_TRANSACTION: defineStorageKey({ + logicalName: "AUTH_REDIRECT_TRANSACTION", + scope: "auth", + name: "oidc-pkce-transaction", + backend: "external", + classification: "opaque-cache", + schemaVersion: 1, + valueCodec: "none", + ttl: "session", + migration: "discard", + quotaFallback: "no-persist", + }), }); export function defineStorageKey( diff --git a/tests/recipes/oidc-pkce-session-owner.test.ts b/tests/recipes/oidc-pkce-session-owner.test.ts index d05a2610..e8903de4 100644 --- a/tests/recipes/oidc-pkce-session-owner.test.ts +++ b/tests/recipes/oidc-pkce-session-owner.test.ts @@ -3,6 +3,7 @@ import { createHash } from "node:crypto"; import { describe, expect, it, vi } from "vitest"; import type { SessionOwnerFetch } from "../../src/bootstrap/product-composition-contract.ts"; +import { STORAGE_REGISTRY } from "../../src/contracts/storage-keys.ts"; import { createOidcPkceSessionOwner, OIDC_PKCE_TRANSACTION_KEY, @@ -193,6 +194,14 @@ describe("OIDC PKCE session owner: sign-in", () => { expect(transaction.returnTo).toBe("/items?limit=1"); expect(transaction.verifier).toMatch(/^[A-Za-z0-9_-]{43}$/u); expect(setup.storage.size).toBe(1); + // 1105/05-01. The key is the storage registry's row, so it follows the + // app's APP_NAMESPACE instead of a literal `ca-frontend:` prefix. + expect([...setup.storage.keys()]).toEqual([ + STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION.physicalKey, + ]); + expect(OIDC_PKCE_TRANSACTION_KEY).toBe( + STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION.physicalKey, + ); }); it("returns only to a path of this app", async () => { diff --git a/tests/unit/storage-registry.test.ts b/tests/unit/storage-registry.test.ts index 44e03db1..e2661138 100644 --- a/tests/unit/storage-registry.test.ts +++ b/tests/unit/storage-registry.test.ts @@ -200,6 +200,44 @@ describe("storage registry", () => { ); }); + // 1105/05-01. The OIDC PKCE recipe wrote its sessionStorage key as a + // literal outside the registry, so renaming APP_NAMESPACE split it off. The + // key is now a registry row the recipe reads, and StoragePort refuses it + // like the pulse key. + it("registers the PKCE sign-in transaction key as externally owned and refuses it", () => { + const transaction = STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION; + const raw = JSON.stringify({ state: "s", nonce: "n" }); + const { storage, values, setItem, removeItem } = createStorage({ + initial: { [transaction.physicalKey]: raw }, + }); + const adapter = createBrowserStorageAdapter({ sessionStorage: storage }); + + expect(transaction).toMatchObject({ + scope: "auth", + name: "oidc-pkce-transaction", + backend: "external", + valueCodec: "none", + }); + expect(transaction.physicalKey).toBe( + buildPhysicalKey("auth", 1, "oidc-pkce-transaction"), + ); + expect(adapter.read("AUTH_REDIRECT_TRANSACTION")).toMatchObject({ + ok: false, + }); + expect(adapter.write("AUTH_REDIRECT_TRANSACTION", "hello")).toMatchObject({ + ok: false, + }); + expect(adapter.remove("AUTH_REDIRECT_TRANSACTION")).toMatchObject({ + ok: false, + }); + expect(setItem).not.toHaveBeenCalled(); + expect(removeItem).not.toHaveBeenCalled(); + expect(values.get(transaction.physicalKey)).toBe(raw); + expect(() => getStorageDefinition("AUTH_REDIRECT_TRANSACTION")).toThrow( + "Externally owned storage key: AUTH_REDIRECT_TRANSACTION", + ); + }); + it("rejects a value codec on an externally owned key", () => { expect(() => defineStorageKey({