testing/cross_backend/credential_conformance.ts

The credential conformance table, and the cross-backend suite that runs it through each backend's _testing_credential_read action.

credential_conformance.json (beside this module) is the one statement of how both spines read the three credential headers — the session cookie in Cookie, the API token in Authorization: Bearer, the daemon token in X-Daemon-Token (auth/credential_headers.ts, the Rust fuz_auth::credential_headers). It holds two tables:

  • rows — {name, lines, read, authenticates, clears_session_cookie}: a request's credential header lines (each Name: value; a name may repeat), how each credential leg reads them (read), and what a request carrying them observably does — which credential authenticates it (null for none) and whether the response clears the session cookie.
  • refused — {name, lines, reason}: lines that are no header lines at all, or more or longer lines than the action reads (TESTING_CREDENTIAL_READ_LINES_MAX, TESTING_CREDENTIAL_READ_LINE_LENGTH_MAX), which _testing_credential_read refuses with invalid_params and that reason.

A line is bytes, one per character: a character U+0080–U+00FF is that byte on the wire, which a runtime hands a handler as the same character.

Live values are per run, so lines and expected tokens name them with {placeholders} (CredentialConformancePlaceholders), which each leg fills from its own keyring and credentials. The legs:

  • the TS unit test, through the action's input schema and run_testing_credential_read;
  • the Rust unit test in fuz_testing, over a byte-identical copy of the file (fuz_app's cross-backend parity project holds the two copies byte-equal);
  • describe_credential_conformance_cross_tests here, sending every row to a backend's _testing_credential_read action;
  • credential_conformance_wire.ts, sending each row's lines as a real request and asserting authenticates and clears_session_cookie.

A row may carry a note for the reader. Edited by hand, never generated.

view source

Declarations
#

17 declarations

assert_credential_conformance
#

testing/cross_backend/credential_conformance.ts view source

(checks: readonly CredentialConformanceCheck[], answers: readonly unknown[], backend: string): void import {assert_credential_conformance} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Compare each check's reading with its expectation and fail once, listing every row that disagrees. Tokens are named by placeholder in the message, never printed.

checks

the table's checks

answers

the reading each check got, in order

type readonly unknown[]

backend

the name the failure message gives the answerer

type string

returns

void

build_credential_conformance_placeholders
#

testing/cross_backend/credential_conformance.ts view source

(input: CredentialConformancePlaceholderInput): Promise<Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | ... 4 more ... | "session_cookie_rowless", string>>> import {build_credential_conformance_placeholders} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Build one leg's placeholder values: the given live credentials, and the cookie spellings derived from them or signed with the reader's keyring.

  • session_cookie_percent_encoded — encodeURIComponent of the valid cookie, what a framework's cookie serializer writes;
  • session_cookie_bad_mac — the valid cookie with its signature's first character changed;
  • session_cookie_expired — a signed payload whose expiry is an hour gone;
  • session_cookie_empty_identity — a signed payload with no identity;
  • session_cookie_rowless — a signed, unexpired payload naming a session token no row holds.

input

the live credentials and the keyring

returns

Promise<Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless", string>>>

the value of every placeholder

throws

  • Error - when a derived spelling would equal the valid cookie, which would make its row vacuous

create_credential_conformance_keyring
#

testing/cross_backend/credential_conformance.ts view source

(cookie_keys: string): Keyring import {create_credential_conformance_keyring} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Build the keyring a backend verifies cookies with, from its SECRET_FUZ_COOKIE_KEYS value.

cookie_keys

the backend's SECRET_FUZ_COOKIE_KEYS

type string

returns

Keyring

throws

  • Error - when the value is no valid keyring

CREDENTIAL_CONFORMANCE_PLACEHOLDERS
#

testing/cross_backend/credential_conformance.ts view source

readonly ["cookie_name", "cookie_name_upper", "session_cookie", "session_cookie_percent_encoded", "session_cookie_bad_mac", "session_cookie_expired", "session_cookie_empty_identity", "session_cookie_rowless", "api_token", "daemon_token"] import {CREDENTIAL_CONFORMANCE_PLACEHOLDERS} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

The placeholder names a row may use, each written {name} in the table.

CREDENTIAL_CONFORMANCE_URL
#

CredentialConformance
#

testing/cross_backend/credential_conformance.ts view source

value + type

{ rows: { name: string; lines: string[]; read: { session_cookie: "invalid" | "absent" | "valid"; bearer_token: string | null; daemon_token: string | null; }; authenticates: "session" | "api_token" | "daemon_token" | null; clears_session_cookie: boolean; note?: string | undefined; }[]; refused: { ...; }[]; } import {CredentialConformance} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

The conformance table, a @fuzdev/fuz_schema object.

rows

type CredentialConformanceRow[]

refused

type CredentialConformanceRefusedRow[]

CredentialConformanceCheck
#

testing/cross_backend/credential_conformance.ts view source

CredentialConformanceCheck import type {CredentialConformanceCheck} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

One read row with its placeholders filled.

label

The row's name, for a failure message.

type string

readonly

row

The row as the table states it.

type CredentialConformanceRow

readonly

lines

The row's lines, filled.

type string[]

readonly

expected

The row's read, its tokens filled.

type TestingCredentialReadOutput

readonly

CredentialConformanceCrossTestOptions
#

testing/cross_backend/credential_conformance.ts view source

CredentialConformanceCrossTestOptions import type {CredentialConformanceCrossTestOptions} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

setup_test

Per-test fixture producer (cross-process).

type (): Promise<TestFixture>

readonly
returns Promise<TestFixture>

cookie_name

The spine's session cookie name (handle.config.cookie_name).

type string

readonly

cookie_keys

The backend's SECRET_FUZ_COOKIE_KEYS value (handle.config.env.SECRET_FUZ_COOKIE_KEYS) — the suite signs the cookie spellings the table names with its primary key.

type string

readonly

daemon_token

A valid daemon token (keeper) — handle.daemon_token.

type string

readonly

rpc_path?

JSON-RPC endpoint path. Default SPINE_RPC_PATH.

type string

readonly

CredentialConformancePlaceholder
#

testing/cross_backend/credential_conformance.ts view source

"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless"

type "api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless"

import type {CredentialConformancePlaceholder} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

A placeholder name — see CREDENTIAL_CONFORMANCE_PLACEHOLDERS.

CredentialConformancePlaceholderInput
#

testing/cross_backend/credential_conformance.ts view source

CredentialConformancePlaceholderInput import type {CredentialConformancePlaceholderInput} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

What build_credential_conformance_placeholders builds the values from.

cookie_name

The session cookie's name.

type string

readonly

session_cookie

A signed session cookie value the reader's keyring verifies — on a live backend, one whose auth_session row exists.

type string

readonly

api_token

A well-formed API token — on a live backend, one that authenticates.

type string

readonly

daemon_token

A well-formed daemon token — on a live backend, the keeper's.

type string

readonly

keyring

The keyring the reader verifies with, to sign the other cookie spellings.

type Keyring

readonly

CredentialConformancePlaceholders
#

testing/cross_backend/credential_conformance.ts view source

Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless", string>>

type Readonly<Record<CredentialConformancePlaceholder, string>>

import type {CredentialConformancePlaceholders} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

The value each placeholder takes on one leg.

api_token

type string

readonly

daemon_token

type string

readonly

session_cookie

type string

readonly

cookie_name

type string

readonly

cookie_name_upper

type string

readonly

session_cookie_percent_encoded

type string

readonly

session_cookie_bad_mac

type string

readonly

session_cookie_expired

type string

readonly

session_cookie_empty_identity

type string

readonly

session_cookie_rowless

type string

readonly

CredentialConformanceRefusedRow
#

testing/cross_backend/credential_conformance.ts view source

value + type

{ name: string; lines: string[]; reason: "invalid_header_line"; note?: string | undefined; } import {CredentialConformanceRefusedRow} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

A refused row: lines _testing_credential_read refuses — no header lines, or past its caps.

name

type string

lines

type string[]

reason

type "invalid_header_line"

note?

type string

CredentialConformanceRow
#

testing/cross_backend/credential_conformance.ts view source

value + type

{ name: string; lines: string[]; read: { session_cookie: "invalid" | "absent" | "valid"; bearer_token: string | null; daemon_token: string | null; }; authenticates: "session" | "api_token" | "daemon_token" | null; clears_session_cookie: boolean; note?: string | undefined; } import {CredentialConformanceRow} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

A read row: header lines, each leg's reading of them, and the observable outcome of a request carrying them.

name

type string

lines

type string[]

read

type TestingCredentialReadOutput

authenticates

The credential that authenticates the request, null when none does.

type "session" | "api_token" | "daemon_token" | null

clears_session_cookie

Whether the response carries the clearing session Set-Cookie.

type boolean

note?

type string

describe_credential_conformance_cross_tests
#

testing/cross_backend/credential_conformance.ts view source

(options: CredentialConformanceCrossTestOptions): void import {describe_credential_conformance_cross_tests} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Register the credential conformance suite: every row of the committed table, sent to the backend's _testing_credential_read action over the keeper's daemon-token channel, must get the reading the table names, and every refused row the invalid_params refusal with its reason. The suite skips itself on a backend that doesn't declare the action.

The lines travel as JSON strings, each character one byte, so a row with a non-ASCII byte reaches the action as it would reach a handler.

options

returns

void

fill_credential_conformance_placeholders
#

testing/cross_backend/credential_conformance.ts view source

(text: string, placeholders: Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless", string>>): string import {fill_credential_conformance_placeholders} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Fill a table string's {placeholders}.

text

a header line or an expected token

type string

placeholders

the leg's values

type Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless", string>>

returns

string

text with each placeholder replaced

throws

  • Error - on a `{name}` that is no known placeholder

load_credential_conformance
#

testing/cross_backend/credential_conformance.ts view source

(): { rows: { name: string; lines: string[]; read: { session_cookie: "invalid" | "absent" | "valid"; bearer_token: string | null; daemon_token: string | null; }; authenticates: "session" | "api_token" | "daemon_token" | null; clears_session_cookie: boolean; note?: string | undefined; }[]; refused: { ...; }[]; } import {load_credential_conformance} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Read and validate the committed conformance table.

returns

CredentialConformance

the parsed table

throws

  • Error - when the file doesn't match `CredentialConformance`

to_credential_conformance_checks
#

testing/cross_backend/credential_conformance.ts view source

(table: { rows: { name: string; lines: string[]; read: { session_cookie: "invalid" | "absent" | "valid"; bearer_token: string | null; daemon_token: string | null; }; authenticates: "session" | "api_token" | "daemon_token" | null; clears_session_cookie: boolean; note?: string | undefined; }[]; refused: { ...; }[]; }, placeholders: Readonly<...>): CredentialConformanceCheck[] import {to_credential_conformance_checks} from '@fuzdev/fuz_app/testing/cross_backend/credential_conformance.js';

Fill every read row's lines and expected tokens.

table

the conformance table

placeholders

the leg's values

type Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "cookie_name_upper" | "session_cookie_percent_encoded" | "session_cookie_bad_mac" | "session_cookie_expired" | "session_cookie_empty_identity" | "session_cookie_rowless", string>>

returns

CredentialConformanceCheck[]

one check per read row, in table order

Depends on
#

Imported by
#