Files
clean-architecture-frontend…/tests/unit/web-push-codec.test.ts
T
DongHyeonkaandClaude Opus 5.5 ec71b0b0a2 refactor(web-push): merge codec primitives into one module and inject the page document (Q-6.6-12)
web-push/codec-primitives.ts now owns OPAQUE_ID/validOpaqueId, isRecord,
hasExactKeys, exactRecord, validAuthority, base64UrlDecode and (to share the
alphabet) base64UrlEncode. push-codec,
push-registration-gateway, push-association-fence-store,
push-subscription-adapter and service-worker-runtime import them instead of
carrying their own copies (the fence store's control/association key checks
now use exactRecord/hasExactKeys with the same key lists). The duplicate-key
JSON scan in push-codec.ts is untouched (realtime lane, T76).

Where the copies differed, the stricter validated behavior is kept:
- validAuthority: the fence store's null guard. The gateway's copy threw a
  TypeError for a null authority, so register()/reconcile() rejected instead
  of returning INVALID_INPUT; they now return INVALID_INPUT (the only change a
  caller can observe; characterization test was RED before the merge).
  Non-record values (arrays) are also refused.
- base64UrlDecode: the gateway's decoder, which refuses a lone trailing
  character (length % 4 == 1). The window adapter's copy accepted it when the
  spare bits were zero; its only caller pre-checks an 87-char VAPID key, so
  that difference was not reachable. `>>` vs `>>>` gave identical bytes.
- OPAQUE_ID, isRecord/hasExactKeys/exactRecord were already identical.

Page controller: PageControllerDependencies gains optional `document`; the
6-hour update check reads it (falling back to the global document), and
bootstrap/register-service-worker.ts now passes host.document through.

New adapter file: INVENTORY.md row 126 + renumber, total 137/137; detail row in
docs/reviews/adapters/05-service-worker-and-web-push.md.

Verified: characterization tests pinned the caller-visible behavior of every
copy before the merge (spare-bit keys, VAPID key, null authority in fence
store and gateway, array/extra-key backend answers, opaque ids); all pass
after, plus direct base64UrlDecode tests and an encode round-trip against
Node's base64url for lengths 0..66. Document injection test was RED
(update() ran while the injected document was hidden), green after. Gates:
check:architecture, types app/test/service-worker, lint, test:unit (only
pre-existing removal-fixture failure), test:component,
check:realtime-boundaries, check:adapter-inventory.
Realtime reference bundle (check:optional-recipes:source, already over budget
at b953142): 40139 -> 40097 gzip bytes after T89+T90.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:37:56 +09:00

396 lines
13 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
WEB_PUSH_PROTOCOLS,
webPushSuccess,
} from "../../src/contracts/web-push.ts";
import {
clickDataFromHint,
decodeNotificationClickData,
decodeWebPushHint,
} from "../../src/adapters/web-push/push-codec.ts";
import {
createAssociationNotificationTag,
createWebPushNotificationRegistry,
} from "../../src/adapters/web-push/notification-registry.ts";
import {
WEB_PUSH_REGISTRATION_OPERATIONS,
createWebPushRegistrationGateway,
type WebPushRegistrationExecutor,
} from "../../src/adapters/web-push/push-registration-gateway.ts";
import { createPushAssociationFenceStore } from "../../src/adapters/web-push/push-association-fence-store.ts";
import { createWebPushSubscriptionAdapter } from "../../src/adapters/web-push/push-subscription-adapter.ts";
import { createFakePushControlStoreDependencies } from "../helpers/fake-push-control-repository.ts";
import {
base64UrlDecode,
base64UrlEncode,
} from "../../src/adapters/web-push/codec-primitives.ts";
const now = Date.parse("2026-07-28T00:00:00.000Z");
function hint(overrides: Readonly<Record<string, unknown>> = {}) {
return {
protocol: WEB_PUSH_PROTOCOLS.hint,
notificationType: "INBOX_ACTIVITY",
notificationId: "notification_01",
associationEpoch: "association_01",
releaseEpoch: "release_01",
issuedAt: "2026-07-27T23:59:00.000Z",
expiresAt: "2026-07-28T01:00:00.000Z",
routeIntent: "OPEN_INBOX",
...overrides,
};
}
function encoded(value: unknown): Uint8Array {
return new TextEncoder().encode(JSON.stringify(value));
}
describe("Web Push contracts", () => {
it("decodes an exact bounded hint and persists only typed click data", () => {
const decoded = decodeWebPushHint(encoded(hint()), now);
expect(decoded).toEqual({ ok: true, value: hint() });
if (!decoded.ok) throw new Error("expected a decoded hint");
const click = clickDataFromHint(decoded.value);
expect(decodeNotificationClickData(click, now)).toEqual({
ok: true,
value: click,
});
expect(click).not.toHaveProperty("notificationType");
expect(click).not.toHaveProperty("issuedAt");
});
it("fails closed for declarative, unknown, expired, and oversized payloads", () => {
expect(
decodeWebPushHint(encoded({ web_push: 8030 }), now),
).toMatchObject({
ok: false,
error: { code: "DECLARATIVE_PUSH_FORBIDDEN" },
});
expect(
decodeWebPushHint(encoded(hint({ unexpected: true })), now),
).toMatchObject({
ok: false,
error: { code: "CONTRACT_REJECTED" },
});
expect(
decodeWebPushHint(
encoded(
hint({
issuedAt: "2026-07-27T22:00:00.000Z",
expiresAt: "2026-07-27T23:00:00.000Z",
}),
),
now,
),
).toMatchObject({
ok: false,
error: { code: "EXPIRED" },
});
expect(
decodeWebPushHint(new Uint8Array(3 * 1024 + 1), now),
).toMatchObject({
ok: false,
error: { code: "LIMIT_EXCEEDED" },
});
expect(
decodeWebPushHint(
encoded(
hint({
issuedAt: "2026-07-28T00:06:00.000Z",
expiresAt: "2026-07-28T01:00:00.000Z",
}),
),
now,
),
).toMatchObject({
ok: false,
error: { code: "CONTRACT_REJECTED" },
});
expect(
decodeWebPushHint(
encoded(
hint({
issuedAt: "2026-07-28T00:00:00.000Z",
expiresAt: "2026-07-29T00:00:00.001Z",
}),
),
now,
),
).toMatchObject({
ok: false,
error: { code: "CONTRACT_REJECTED" },
});
const duplicateNotificationId = JSON.stringify(hint()).replace(
'"notificationId":"notification_01"',
'"notificationId":"notification_old","notificationId":"notification_01"',
);
expect(
decodeWebPushHint(
new TextEncoder().encode(duplicateNotificationId),
now,
),
).toMatchObject({
ok: false,
error: { code: "CONTRACT_REJECTED" },
});
});
it("uses an injected closed notification and route registry", async () => {
const registry = createWebPushNotificationRegistry([
{
notificationType: "INBOX_ACTIVITY",
routeIntent: "OPEN_INBOX",
title: "새 알림이 있습니다",
body: "앱을 열어 최신 내용을 확인하세요.",
path: "/inbox",
},
]);
expect(
registry.resolve("INBOX_ACTIVITY", "OPEN_INBOX"),
).toMatchObject({ path: "/inbox" });
expect(registry.resolve("UNKNOWN", "OPEN_INBOX")).toBeNull();
expect(registry.routePath("OPEN_INBOX")).toBe("/inbox");
const tag = await createAssociationNotificationTag(
"association_01",
"INBOX_ACTIVITY",
async () => new Uint8Array(32).fill(7).buffer,
);
expect(tag).toMatch(/^ca-push-v1-[0-9a-f]{24}-inbox_activity$/u);
expect(tag).not.toContain("association_01");
});
it("binds backend calls to fixed operations and strict response codecs", async () => {
const calls: Array<Readonly<{ operationId: string; body: unknown }>> = [];
const executor: WebPushRegistrationExecutor = {
async execute(input) {
calls.push(input);
switch (input.operationId) {
case WEB_PUSH_REGISTRATION_OPERATIONS.register:
return webPushSuccess({
protocol: WEB_PUSH_PROTOCOLS.registration,
associationEpoch: "association_01",
sessionBindingEpoch: "session_01",
});
case WEB_PUSH_REGISTRATION_OPERATIONS.reconcile:
return webPushSuccess({
protocol: WEB_PUSH_PROTOCOLS.reconciliation,
state: "ABSENT",
});
case WEB_PUSH_REGISTRATION_OPERATIONS.revoke:
return webPushSuccess({
protocol: WEB_PUSH_PROTOCOLS.revoke,
state: "ALREADY_GONE",
});
}
},
};
const gateway = createWebPushRegistrationGateway(executor);
const p256dh = new Uint8Array(65);
p256dh[0] = 4;
const material = {
endpoint: "https://push.example.test/subscription/opaque",
p256dh: Buffer.from(p256dh).toString("base64url"),
auth: Buffer.from(new Uint8Array(16)).toString("base64url"),
expirationTime: null,
};
const authority = {
fenceGeneration: "fence_01",
sessionBindingEpoch: "session_01",
releaseEpoch: "release_01",
};
expect(
await gateway.register({
material,
authority,
idempotencyKey: "idempotency_01",
}),
).toEqual({
ok: true,
value: {
associationEpoch: "association_01",
sessionBindingEpoch: "session_01",
},
});
expect(await gateway.reconcile({ material, authority })).toEqual({
ok: true,
value: { state: "ABSENT" },
});
expect(
await gateway.revoke({ associationEpoch: "association_01" }),
).toEqual({
ok: true,
value: { state: "ALREADY_GONE" },
});
expect(calls.map((call) => call.operationId)).toEqual([
WEB_PUSH_REGISTRATION_OPERATIONS.register,
WEB_PUSH_REGISTRATION_OPERATIONS.reconcile,
WEB_PUSH_REGISTRATION_OPERATIONS.revoke,
]);
expect(
await gateway.register({
material: {
...material,
p256dh: Buffer.from(new Uint8Array(65)).toString(
"base64url",
),
},
authority,
idempotencyKey: "idempotency_02",
}),
).toMatchObject({
ok: false,
error: { code: "INVALID_INPUT" },
});
const throwing = createWebPushRegistrationGateway({
async execute() {
throw new Error("native transport detail must not escape");
},
});
expect(
await throwing.revoke({
associationEpoch: "association_01",
}),
).toMatchObject({
ok: false,
error: { code: "NATIVE_FAILURE" },
});
});
});
/**
* Q-6.6-12. The web-push files each carried their own base64url decoder,
* opaque-id pattern, authority check and exact-record check. These pin what
* every caller observes, so merging them into one module cannot loosen any.
*/
describe("web-push codec primitives as seen by their callers (Q-6.6-12)", () => {
const authority = {
fenceGeneration: "fence_01",
sessionBindingEpoch: "session_01",
releaseEpoch: "release_01",
};
const p256dhBytes = new Uint8Array(65);
p256dhBytes[0] = 4;
const material = {
endpoint: "https://push.example.test/subscription/opaque",
p256dh: Buffer.from(p256dhBytes).toString("base64url"),
auth: Buffer.from(new Uint8Array(16)).toString("base64url"),
expirationTime: null,
};
/** 87 chars carry 2 spare bits and 22 chars carry 4; they must be zero. */
const withSpareBitSet = (encoded: string) =>
`${encoded.slice(0, -1)}${encoded.endsWith("A") ? "B" : "A"}`;
const registered: WebPushRegistrationExecutor = {
async execute() {
return webPushSuccess({
protocol: WEB_PUSH_PROTOCOLS.registration,
associationEpoch: "association_01",
sessionBindingEpoch: "session_01",
});
},
};
it("rejects subscription keys whose spare base64url bits are set", async () => {
const gateway = createWebPushRegistrationGateway(registered);
for (const broken of [
{ ...material, p256dh: withSpareBitSet(material.p256dh) },
{ ...material, auth: withSpareBitSet(material.auth) },
]) {
expect(
await gateway.register({
material: broken,
authority,
idempotencyKey: "idempotency_01",
}),
).toMatchObject({ ok: false, error: { code: "INVALID_INPUT" } });
}
});
it("rejects a VAPID key whose spare base64url bits are set", () => {
const key = new Uint8Array(65);
key[0] = 4;
const valid = Buffer.from(key).toString("base64url");
expect(() =>
createWebPushSubscriptionAdapter({
vapidPublicKey: withSpareBitSet(valid),
} as never),
).toThrow(TypeError);
});
it("rejects a null authority as invalid input in the fence store", async () => {
const store = createPushAssociationFenceStore(
createFakePushControlStoreDependencies(),
);
expect(
await store.prepare({
authority: null as never,
updatedAt: "2026-07-28T00:00:00.000Z",
}),
).toMatchObject({ ok: false, error: { code: "INVALID_INPUT" } });
});
it("rejects a null authority as invalid input in the gateway", async () => {
const gateway = createWebPushRegistrationGateway(registered);
await expect(
gateway.register({
material,
authority: null as never,
idempotencyKey: "idempotency_01",
}),
).resolves.toMatchObject({ ok: false, error: { code: "INVALID_INPUT" } });
await expect(
gateway.reconcile({ material, authority: null as never }),
).resolves.toMatchObject({ ok: false, error: { code: "INVALID_INPUT" } });
});
it("rejects backend answers that are arrays or carry extra keys", async () => {
for (const answer of [
[WEB_PUSH_PROTOCOLS.revoke, "REVOKED"],
{ protocol: WEB_PUSH_PROTOCOLS.revoke, state: "REVOKED", extra: 1 },
]) {
const gateway = createWebPushRegistrationGateway({
execute: async () => webPushSuccess(answer),
});
expect(
await gateway.revoke({ associationEpoch: "association_01" }),
).toMatchObject({ ok: false, error: { code: "CONTRACT_REJECTED" } });
}
});
it("gives every accepted base64url string exactly one decoding", () => {
expect([...base64UrlDecode("AQID")!]).toEqual([1, 2, 3]);
expect([...base64UrlDecode("AQ")!]).toEqual([1]);
expect(base64UrlDecode("")?.byteLength).toBe(0);
// "AQIDA": a lone trailing character cannot finish a byte. The window
// adapter's old copy accepted it because its spare bits were zero.
for (const invalid of ["A", "AQIDA", "AR", "AQ==", "AQ+/", null, 7]) {
expect(base64UrlDecode(invalid), String(invalid)).toBeNull();
}
});
it("encodes base64url exactly like Node and round-trips through the decoder", () => {
for (let length = 0; length <= 66; length += 1) {
const bytes = Uint8Array.from({ length }, (_, index) => (index * 37 + 11) & 255);
const encoded = base64UrlEncode(bytes);
expect(encoded).toBe(Buffer.from(bytes).toString("base64url"));
expect([...base64UrlDecode(encoded)!]).toEqual([...bytes]);
}
});
it("rejects opaque ids outside the shared pattern", async () => {
const gateway = createWebPushRegistrationGateway(registered);
for (const associationEpoch of ["", "-leading", "a b", "a".repeat(129)]) {
expect(await gateway.revoke({ associationEpoch })).toMatchObject({
ok: false,
error: { code: "INVALID_INPUT" },
});
}
expect(
decodeWebPushHint(encoded(hint({ notificationId: "a b" })), now),
).toMatchObject({ ok: false });
});
});