Files
clean-architecture-frontend…/src/contracts/rest-profiles.ts
T
DongHyeonkaandClaude Opus 5.5 375b563961 fix(contracts): refuse IPv6, mapped, CGNAT and internal hosts at admission (Q-6.7-10)
Production admission only knew IPv4 private ranges and `localhost`, so
`[::ffff:127.0.0.1]`, `[fd00::1]`, `[fe80::1]`, `100.64.0.1`,
`0.1.2.3`, `api.internal`, `printer.local` and a trailing-dot
`localhost.` were all admitted as public API endpoints.

isNonPublicHost now also refuses 0.0.0.0/8, 100.64.0.0/10 (CGNAT),
IPv6 unique-local (fc00::/7), link-local (fe80::/10), every IPv4-mapped
address (::ffff:0:0/96), and `.local` / `.internal` names, after
stripping one trailing dot. URL.hostname already canonicalises the
literals, so no separate IP parser is needed.

The loopback list that allows plain http (`localhost`, `127.0.0.1`,
`[::1]`) now lives once in deployment-admission.ts
(LOOPBACK_HOSTNAMES / isLoopbackHostname); rest-profiles.ts and
browser-rpc.ts use it instead of their own copies (same list, no
behavior change there).

Verified: new cases in tests/unit/deployment-admission.test.ts; a probe
showed 13 of the 14 forms admitted before and all refused after, while
2001:db8::1, fec0::1, 100.63/100.128 and *.example.com names stay
admitted. Gates green except the known removal-fixture test.

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

355 lines
11 KiB
TypeScript

import {
createReadOnlyRegistry,
type ReadOnlyRegistry,
} from "./read-only-registry.ts";
import { snapshotExactArray, snapshotExactObject } from "./exact-snapshot.ts";
import { isLoopbackHostname } from "./deployment-admission.ts";
export type FetchCredentialsMode = "omit" | "same-origin" | "include";
export type RestProviderProfile = Readonly<{
providerId: string;
baseUrl: string;
allowedCredentialsModes: readonly FetchCredentialsMode[];
redirect: "error";
referrerPolicy: "no-referrer";
}>;
/**
* VD-23. The complete closed set of headers a credential owner may contribute.
* Transport-owned headers (`accept`, `content-type`, `idempotency-key`) and
* every forbidden request header are deliberately absent.
*/
export const CREDENTIAL_HEADER_NAMES = Object.freeze([
"authorization",
"x-csrf-token",
"x-tenant-context",
] as const);
export type CredentialHeaderName = (typeof CREDENTIAL_HEADER_NAMES)[number];
export type RestAuthProfile = Readonly<{
authProfileId: string;
transport: "ANONYMOUS" | "BEARER_HEADER" | "SAME_ORIGIN_COOKIE";
credentials: FetchCredentialsMode;
allowedCredentialHeaders: readonly CredentialHeaderName[];
/**
* Proof headers the transport must observe before dispatch. A missing entry
* fails closed with zero `fetch()` calls rather than sending an anonymous
* request under an authenticated profile.
*/
requiredCredentialHeaders: readonly CredentialHeaderName[];
}>;
/**
* LIVE-02. A read facade over a private store, never a `Map`. The executor
* resolves a profile on every request, so a post-installation `clear()` would
* otherwise turn every authenticated call into `UNKNOWN_AUTH_PROFILE`.
*/
export type InstalledRestAuthProfiles = ReadOnlyRegistry<
string,
RestAuthProfile
>;
export type RestCsrfProfile = Readonly<{
csrfProfileId: string;
mode: "NONE" | "HEADER";
headerName: "x-csrf-token" | null;
}>;
export const REST_AUTH_PROFILES = Object.freeze({
REFERENCE_EXTERNAL_BEARER: Object.freeze({
authProfileId: "REFERENCE_EXTERNAL_BEARER",
transport: "BEARER_HEADER",
credentials: "omit",
allowedCredentialHeaders: Object.freeze(["authorization"] as const),
requiredCredentialHeaders: Object.freeze(["authorization"] as const),
}),
ANONYMOUS: Object.freeze({
authProfileId: "ANONYMOUS",
transport: "ANONYMOUS",
credentials: "omit",
allowedCredentialHeaders: Object.freeze([]),
requiredCredentialHeaders: Object.freeze([]),
}),
} satisfies Readonly<Record<string, RestAuthProfile>>);
function isCredentialHeaderName(value: unknown): value is CredentialHeaderName {
return (
typeof value === "string" &&
(CREDENTIAL_HEADER_NAMES as readonly string[]).includes(value)
);
}
function exactHeaderSet(
source: unknown,
label: string,
): readonly CredentialHeaderName[] {
// Q-6.7-6. Copied by index, so the set that is checked is the set installed.
const names = snapshotExactArray(source);
if (!names) {
throw new TypeError(`REST auth profile ${label} must be an array.`);
}
const seen = new Set<string>();
for (const name of names) {
if (!isCredentialHeaderName(name) || seen.has(name)) {
throw new TypeError(`REST auth profile ${label} is not an exact set.`);
}
seen.add(name);
}
return names as readonly CredentialHeaderName[];
}
const AUTH_PROFILE_KEYS = Object.freeze([
"authProfileId",
"transport",
"credentials",
"allowedCredentialHeaders",
"requiredCredentialHeaders",
] as const);
/**
* §7.7 / VD-23. Installs the composition-owned auth profile registry once.
*
* The registry — not a credential collaborator — owns Fetch `credentials` and
* the exact allowed/required credential-header sets. An incoherent profile is a
* composition failure, never a runtime downgrade.
*/
export function installRestAuthProfileRegistry(
profiles: Readonly<Record<string, RestAuthProfile>> = REST_AUTH_PROFILES,
): InstalledRestAuthProfiles {
const installed = new Map<string, RestAuthProfile>();
for (const [key, source] of Object.entries(profiles)) {
// Q-6.7-6. Every check reads one owned snapshot, never the caller's row.
const candidate = snapshotExactObject(source, {
allowed: AUTH_PROFILE_KEYS,
required: AUTH_PROFILE_KEYS,
}) as RestAuthProfile | null;
if (!candidate) {
throw new TypeError(
`REST auth profile ${key} is not an exact own-data object.`,
);
}
const authProfileId = candidate.authProfileId;
if (
typeof authProfileId !== "string" ||
authProfileId.length === 0 ||
authProfileId !== key
) {
throw new TypeError(`REST auth profile ${key} has a mismatched identity.`);
}
const allowed = exactHeaderSet(
candidate.allowedCredentialHeaders,
"allowedCredentialHeaders",
);
const required = exactHeaderSet(
candidate.requiredCredentialHeaders,
"requiredCredentialHeaders",
);
if (!required.every((name) => allowed.includes(name))) {
throw new TypeError(
`REST auth profile ${key} requires a header it does not allow.`,
);
}
const credentials = candidate.credentials;
if (!["omit", "same-origin", "include"].includes(credentials)) {
throw new TypeError(`REST auth profile ${key} has invalid credentials.`);
}
switch (candidate.transport) {
case "ANONYMOUS":
if (
credentials !== "omit" ||
allowed.length > 0 ||
required.length > 0
) {
throw new TypeError(
`Anonymous REST auth profile ${key} cannot carry credentials.`,
);
}
break;
case "BEARER_HEADER":
if (credentials !== "omit" || !required.includes("authorization")) {
throw new TypeError(
`Bearer REST auth profile ${key} must require authorization with omitted credentials.`,
);
}
break;
case "SAME_ORIGIN_COOKIE":
if (credentials === "omit" || allowed.includes("authorization")) {
throw new TypeError(
`Cookie REST auth profile ${key} must send ambient credentials without a bearer header.`,
);
}
break;
default:
throw new TypeError(`REST auth profile ${key} has unknown transport.`);
}
installed.set(
authProfileId,
Object.freeze({
authProfileId,
transport: candidate.transport,
credentials,
allowedCredentialHeaders: allowed,
requiredCredentialHeaders: required,
}),
);
}
if (installed.size === 0) {
throw new TypeError("REST auth profile registry cannot be empty.");
}
const registry = createReadOnlyRegistry(installed);
INSTALLED_REGISTRIES.add(registry);
return registry;
}
/** Registries this module installed, as opposed to look-alike objects. */
const INSTALLED_REGISTRIES = new WeakSet<object>();
/**
* REST auth profiles as accepted by resolve: the installed registry, or a raw
* record that is installed (validated) before any lookup.
*/
export type RestAuthProfileSource =
| InstalledRestAuthProfiles
| Readonly<Record<string, RestAuthProfile>>;
/**
* Q-6.7-9. Composition, the V3 executor and V2 resolve answer from one
* validated registry. A raw record never reaches a lookup unvalidated, so a
* profile installation would refuse cannot be resolved either.
*/
function installedAuthProfiles(
profiles: RestAuthProfileSource,
): InstalledRestAuthProfiles {
return INSTALLED_REGISTRIES.has(profiles)
? (profiles as InstalledRestAuthProfiles)
: installRestAuthProfileRegistry(
profiles as Readonly<Record<string, RestAuthProfile>>,
);
}
/** The single installed registry every composition root shares. */
export const INSTALLED_REST_AUTH_PROFILES: InstalledRestAuthProfiles =
installRestAuthProfileRegistry();
export const REST_CSRF_PROFILES = Object.freeze({
NO_CSRF_BEARER: Object.freeze({
csrfProfileId: "NO_CSRF_BEARER",
mode: "NONE",
headerName: null,
}),
} satisfies Readonly<Record<string, RestCsrfProfile>>);
export function createRestProviderProfile(
providerId: string,
baseUrl: string,
allowedCredentialsModes: readonly FetchCredentialsMode[] = ["omit"],
): RestProviderProfile {
const parsed = new URL(baseUrl);
const localHttp =
parsed.protocol === "http:" &&
isLoopbackHostname(parsed.hostname);
if (
!providerId ||
(parsed.protocol !== "https:" && !localHttp) ||
parsed.username ||
parsed.password ||
parsed.search ||
parsed.hash ||
allowedCredentialsModes.length === 0 ||
new Set(allowedCredentialsModes).size !== allowedCredentialsModes.length
) {
throw new TypeError("Invalid REST provider profile.");
}
return Object.freeze({
providerId,
baseUrl: parsed.href,
allowedCredentialsModes: Object.freeze([...allowedCredentialsModes]),
redirect: "error",
referrerPolicy: "no-referrer",
});
}
export function resolveRestSecurityProfiles(
operation: Readonly<{
method: string;
auth: "none" | "external-session";
authProfileId?: string;
csrfProfileId?: string;
}>,
provider: RestProviderProfile,
authProfiles: RestAuthProfileSource = INSTALLED_REST_AUTH_PROFILES,
csrfProfiles: Readonly<Record<string, RestCsrfProfile>> = REST_CSRF_PROFILES,
): Readonly<{ auth: RestAuthProfile; csrf: RestCsrfProfile }> {
const auth = installedAuthProfiles(authProfiles).get(
operation.authProfileId ?? "",
);
const csrfProfileId = operation.csrfProfileId ?? "";
const csrf = Object.hasOwn(csrfProfiles, csrfProfileId)
? csrfProfiles[csrfProfileId]
: undefined;
const unsafe = !["GET", "HEAD", "OPTIONS"].includes(operation.method);
if (
!auth ||
!csrf ||
!provider.allowedCredentialsModes.includes(auth.credentials) ||
(operation.auth === "none" && auth.transport !== "ANONYMOUS") ||
(operation.auth === "external-session" &&
auth.transport === "ANONYMOUS") ||
(auth.transport === "BEARER_HEADER" && csrf.mode !== "NONE") ||
(unsafe &&
auth.transport === "SAME_ORIGIN_COOKIE" &&
csrf.mode !== "HEADER")
) {
throw new TypeError("REST security profiles are incoherent.");
}
return Object.freeze({ auth, csrf });
}
export function validateRestProfileBindings(
operations: Readonly<
Record<
string,
Readonly<{
contractVersion?: number;
operationId: string;
method: string;
auth: "none" | "external-session";
providerId?: string;
authProfileId?: string;
csrfProfileId?: string;
}>
>
>,
providerCredentialModes: Readonly<
Record<string, readonly FetchCredentialsMode[]>
>,
authProfiles: RestAuthProfileSource = INSTALLED_REST_AUTH_PROFILES,
csrfProfiles: Readonly<Record<string, RestCsrfProfile>> = REST_CSRF_PROFILES,
): true {
const installed = installedAuthProfiles(authProfiles);
for (const operation of Object.values(operations)) {
if (operation.contractVersion !== 2) continue;
const allowed = providerCredentialModes[operation.providerId ?? ""];
if (!allowed) {
throw new TypeError(
`Unregistered REST provider binding: ${operation.operationId}`,
);
}
resolveRestSecurityProfiles(
operation,
Object.freeze({
providerId: operation.providerId ?? "",
baseUrl: "https://contract.invalid/",
allowedCredentialsModes: allowed,
redirect: "error",
referrerPolicy: "no-referrer",
}),
installed,
csrfProfiles,
);
}
return true;
}