@hraness/suite-accounts 0.9.20

package/src/identity/principals.ts

@@ -0,0 +1,301 @@
+import { err, isRecord, ok, type Result } from "@hraness/result";
+import { deepFreeze } from "../immutable.js";
+
+import {
+  parseSuiteAccountId,
+  type SuiteAccountId,
+} from "./identifiers.js";
+import {
+  parseSuiteUsername,
+  type SuiteUsername,
+} from "./usernames.js";
+
+export const SUITE_PRODUCTS = deepFreeze([
+  "soundfish",
+  "hra",
+  "peopleblade",
+  "ghostget",
+  // Compatibility-only readers for retired publication principal evidence.
+  "crclte",
+  "pub",
+] as const);
+export const LEGACY_SUITE_PRODUCT_IDS = deepFreeze([
+  "oprte",
+  "kitchen",
+] as const);
+export const SUITE_ENVIRONMENTS = deepFreeze([
+  "development",
+  "staging",
+  "production",
+] as const);
+export const SUITE_ISSUABLE_ENVIRONMENTS = deepFreeze([
+  "development",
+  "production",
+] as const);
+
+export type SuiteProduct = (typeof SUITE_PRODUCTS)[number];
+export type LegacySuiteProductId =
+  (typeof LEGACY_SUITE_PRODUCT_IDS)[number];
+export type SuiteEnvironment = (typeof SUITE_ENVIRONMENTS)[number];
+export type SuiteIssuableEnvironment =
+  (typeof SUITE_ISSUABLE_ENVIRONMENTS)[number];
+
+declare const identityIssuerBrand: unique symbol;
+declare const identitySubjectBrand: unique symbol;
+
+export type IdentityIssuer = string & {
+  readonly [identityIssuerBrand]: "IdentityIssuer";
+};
+export type IdentitySubject = string & {
+  readonly [identitySubjectBrand]: "IdentitySubject";
+};
+
+export type IssuerSubject = {
+  readonly issuer: IdentityIssuer;
+  readonly subject: IdentitySubject;
+};
+
+export type LegacyPrincipalLink = {
+  readonly environment: SuiteEnvironment;
+  readonly legacySubject: IdentitySubject;
+  readonly product: SuiteProduct;
+};
+
+export type IdentityIssue =
+  | "invalid-audience"
+  | "invalid-environment"
+  | "invalid-issuer"
+  | "invalid-jwt-claims"
+  | "invalid-legacy-link"
+  | "invalid-product"
+  | "invalid-subject"
+  | "invalid-suite-account-id";
+
+const localIssuerHosts = new Set(["127.0.0.1", "[::1]", "localhost"]);
+
+function containsAsciiControl(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127) return true;
+  }
+  return false;
+}
+
+export function parseIdentityIssuer(
+  value: unknown,
+): Result<IdentityIssuer, "invalid-issuer"> {
+  if (typeof value !== "string" || value.length > 2_048 || value.trim() !== value) {
+    return err("invalid-issuer");
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return err("invalid-issuer");
+  }
+  const local = localIssuerHosts.has(parsed.hostname);
+  if (
+    (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) ||
+    parsed.username !== "" ||
+    parsed.password !== "" ||
+    parsed.pathname !== "/" ||
+    parsed.search !== "" ||
+    parsed.hash !== ""
+  ) {
+    return err("invalid-issuer");
+  }
+  return ok(parsed.origin as IdentityIssuer);
+}
+
+export function parseIdentitySubject(
+  value: unknown,
+): Result<IdentitySubject, "invalid-subject"> {
+  if (
+    typeof value !== "string" ||
+    value.length < 1 ||
+    value.length > 255 ||
+    value.trim() !== value ||
+    containsAsciiControl(value)
+  ) {
+    return err("invalid-subject");
+  }
+  return ok(value as IdentitySubject);
+}
+
+export function parseIssuerSubject(
+  value: unknown,
+): Result<IssuerSubject, "invalid-issuer" | "invalid-subject"> {
+  if (!isRecord(value)) return err("invalid-subject");
+  const issuer = parseIdentityIssuer(value["issuer"]);
+  if (!issuer.ok) return issuer;
+  const subject = parseIdentitySubject(value["subject"]);
+  return subject.ok
+    ? ok({ issuer: issuer.value, subject: subject.value })
+    : subject;
+}
+
+export function parseSuiteProduct(
+  value: unknown,
+): Result<SuiteProduct, "invalid-product"> {
+  switch (value) {
+    case "soundfish":
+    case "hra":
+    case "peopleblade":
+    case "ghostget":
+    case "crclte":
+    case "pub":
+      return ok(value);
+    // OPRTE and Kitchen are predecessor product IDs. Parse them only at
+    // foreign or stored boundaries and immediately return the Oompa product
+    // ID `hra` so new state cannot perpetuate either predecessor identity.
+    case "oprte":
+    case "kitchen":
+      return ok("hra");
+    default:
+      return err("invalid-product");
+  }
+}
+
+export function parseSuiteEnvironment(
+  value: unknown,
+): Result<SuiteEnvironment, "invalid-environment"> {
+  return typeof value === "string" &&
+      (SUITE_ENVIRONMENTS as readonly string[]).includes(value)
+    ? ok(value as SuiteEnvironment)
+    : err("invalid-environment");
+}
+
+/**
+ * Staging remains parseable only for legacy stored and signed evidence.
+ * New link, receipt, and identity authority is limited to local development
+ * and the single production deployment.
+ */
+export function isSuiteIssuableEnvironment(
+  value: SuiteEnvironment,
+): value is SuiteIssuableEnvironment {
+  return value === "development" || value === "production";
+}
+
+export function parseLegacyPrincipalLink(
+  value: unknown,
+): Result<LegacyPrincipalLink, IdentityIssue> {
+  if (!isRecord(value)) return err("invalid-legacy-link");
+  const product = parseSuiteProduct(value["product"]);
+  if (!product.ok) return product;
+  const environment = parseSuiteEnvironment(value["environment"]);
+  if (!environment.ok) return environment;
+  const legacySubject = parseIdentitySubject(value["legacySubject"]);
+  if (!legacySubject.ok) return legacySubject;
+  return ok({
+    environment: environment.value,
+    legacySubject: legacySubject.value,
+    product: product.value,
+  });
+}
+
+export type SuiteJwtClaims = {
+  readonly audience: readonly string[];
+  readonly expiresAtSeconds: number;
+  readonly issuedAtSeconds: number;
+  readonly notBeforeSeconds?: number;
+  readonly principal: IssuerSubject;
+  readonly profileComplete: boolean;
+  readonly profileRevision: "username-v1" | null;
+  readonly suiteAccountId: SuiteAccountId;
+  readonly username: SuiteUsername | null;
+};
+
+function parseAudience(value: unknown): Result<readonly string[], "invalid-audience"> {
+  const values = typeof value === "string" ? [value] : value;
+  if (
+    !Array.isArray(values) ||
+    values.length < 1 ||
+    values.length > 8 ||
+    values.some(
+      (entry) =>
+        typeof entry !== "string" ||
+        entry.length < 1 ||
+        entry.length > 255 ||
+        entry.trim() !== entry ||
+        containsAsciiControl(entry),
+    ) ||
+    new Set(values).size !== values.length
+  ) {
+    return err("invalid-audience");
+  }
+  return ok(values as readonly string[]);
+}
+
+function parseTimestamp(value: unknown): number | null {
+  return typeof value === "number" &&
+      Number.isSafeInteger(value) &&
+      value >= 0
+    ? value
+    : null;
+}
+
+/**
+ * Parse a decoded JWT payload from `unknown`.
+ *
+ * This function does not verify a signature, issuer trust, audience ownership, or
+ * current time. Authorization must perform those checks before using the result.
+ */
+export function parseSuiteJwtClaims(
+  value: unknown,
+): Result<SuiteJwtClaims, IdentityIssue> {
+  if (!isRecord(value)) return err("invalid-jwt-claims");
+  const principal = parseIssuerSubject({
+    issuer: value["iss"],
+    subject: value["sub"],
+  });
+  if (!principal.ok) return principal;
+  const suiteAccountId = parseSuiteAccountId(value["suite_account_id"]);
+  if (!suiteAccountId.ok) return suiteAccountId;
+  const audience = parseAudience(value["aud"]);
+  if (!audience.ok) return audience;
+  const issuedAtSeconds = parseTimestamp(value["iat"]);
+  const expiresAtSeconds = parseTimestamp(value["exp"]);
+  const notBeforeSeconds =
+    value["nbf"] === undefined ? undefined : parseTimestamp(value["nbf"]);
+  const legacyProfile = value["profile_revision"] === undefined
+    && value["profile_complete"] === undefined
+    && value["username"] === undefined;
+  const profileRevision = legacyProfile
+    ? null
+    : value["profile_revision"] === "username-v1"
+      ? "username-v1" as const
+      : undefined;
+  const profileComplete = legacyProfile
+    ? false
+    : typeof value["profile_complete"] === "boolean"
+      ? value["profile_complete"]
+      : undefined;
+  const username = legacyProfile || value["username"] === null
+    ? null
+    : parseSuiteUsername(value["username"]);
+  if (
+    issuedAtSeconds === null ||
+    expiresAtSeconds === null ||
+    expiresAtSeconds <= issuedAtSeconds ||
+    notBeforeSeconds === null ||
+    (notBeforeSeconds !== undefined && notBeforeSeconds > expiresAtSeconds) ||
+    profileRevision === undefined ||
+    profileComplete === undefined ||
+    (username !== null && !username.ok) ||
+    profileComplete !== (username !== null)
+  ) {
+    return err("invalid-jwt-claims");
+  }
+  return ok({
+    audience: audience.value,
+    expiresAtSeconds,
+    issuedAtSeconds,
+    ...(notBeforeSeconds === undefined ? {} : { notBeforeSeconds }),
+    principal: principal.value,
+    profileComplete,
+    profileRevision,
+    suiteAccountId: suiteAccountId.value,
+    username: username?.value ?? null,
+  });
+}

package/src/identity/profiles-v2.ts

@@ -0,0 +1,330 @@
+import { err, ok, type Result } from "@hraness/result";
+import { deepFreeze } from "../immutable.js";
+import { getSuiteAccountsDeployment } from "../registry.js";
+import { parseSuiteAccountId, type SuiteAccountId } from "./identifiers.js";
+import {
+  normalizeSuiteProfileLink,
+  parseSuiteProfileUpdateRequest,
+  SUITE_PROFILE_URL_MAX_LENGTH,
+  type SuiteProfileIssue,
+  type SuiteProfileLinkKey,
+  type SuiteProfileLinks,
+} from "./profiles.js";
+import { parseSuiteUsername, type SuiteUsername } from "./usernames.js";
+
+export type SuiteProfileLinkKeyV2 = SuiteProfileLinkKey | "github";
+export type SuiteProfileLinksV2 = Readonly<SuiteProfileLinks & {
+  github: string | null;
+}>;
+declare const suiteAvatarRefBrand: unique symbol;
+/** An opaque syntax-checked reference, not proof of ownership or publication. */
+export type SuiteAvatarRef = string & {
+  readonly [suiteAvatarRefBrand]: "SuiteAvatarRef";
+};
+
+export type SuitePublicProfileV2 = Readonly<{
+  schemaVersion: 2;
+  accountId: SuiteAccountId;
+  username: SuiteUsername;
+  name: string;
+  bio: string;
+  links: SuiteProfileLinksV2;
+  avatarRef: SuiteAvatarRef | null;
+  revision: number;
+}>;
+
+export type SuiteProfileEditorV2 = Readonly<
+  Omit<SuitePublicProfileV2, "username"> & {
+    username: SuiteUsername | null;
+    publication: "private" | "published";
+  }
+>;
+
+export type SuiteProfileUpdateV2 = Readonly<{
+  schemaVersion: 2;
+  expectedRevision: number;
+  name: string;
+  bio: string;
+  links: SuiteProfileLinksV2;
+  avatarRef: SuiteAvatarRef | null;
+  publication: "publish" | "private";
+}>;
+
+export type SuiteProfileV2Issue = Readonly<{
+  field:
+    | SuiteProfileLinkKeyV2
+    | "accountId"
+    | "avatarRef"
+    | "bio"
+    | "expectedRevision"
+    | "name"
+    | "profile"
+    | "publication"
+    | "revision"
+    | "schemaVersion"
+    | "username";
+  reason: "invalid" | "required" | "too_long";
+}>;
+
+const LINK_KEYS = [
+  "bluesky", "github", "instagram", "linkedin", "telegram", "website", "x",
+] as const;
+const PUBLIC_KEYS = [
+  "schemaVersion", "accountId", "username", "name", "bio", "links",
+  "avatarRef", "revision",
+] as const;
+const EDITOR_KEYS = [...PUBLIC_KEYS, "publication"] as const;
+const UPDATE_KEYS = [
+  "schemaVersion", "expectedRevision", "name", "bio", "links", "avatarRef",
+  "publication",
+] as const;
+// Bound work before text normalization. HTTP callers must also cap their body.
+const MAX_INPUT_TEXT_LENGTH = 32_768;
+const AVATAR_PATTERN = /^avref_(?!0{64}$)[0-9a-f]{64}$/u;
+
+function issue(
+  field: SuiteProfileV2Issue["field"] = "profile",
+  reason: SuiteProfileV2Issue["reason"] = "invalid",
+): Result<never, SuiteProfileV2Issue> {
+  return deepFreeze(err({ field, reason }));
+}
+
+function success<Value>(value: Value): Result<Value, SuiteProfileV2Issue> {
+  return deepFreeze(ok(value));
+}
+
+/** Copy data descriptors without evaluating getters or retaining caller records. */
+function snapshot(
+  value: unknown,
+  keys: readonly string[],
+): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const prototype: unknown = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return null;
+  const actual = Reflect.ownKeys(value);
+  if (actual.length !== keys.length) return null;
+  const copy = Object.create(null) as Record<string, unknown>;
+  for (const key of actual) {
+    if (typeof key !== "string" || !keys.includes(key)) return null;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      return null;
+    }
+    const field: unknown = descriptor.value;
+    copy[key] = field;
+  }
+  return copy;
+}
+
+function nonnegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+export function parseSuiteAvatarRef(
+  value: unknown,
+): Result<SuiteAvatarRef, SuiteProfileV2Issue> {
+  return typeof value === "string" && value.length === 70 && AVATAR_PATTERN.test(value)
+    ? success(value as SuiteAvatarRef)
+    : issue("avatarRef");
+}
+
+function optionalAvatar(value: unknown): Result<SuiteAvatarRef | null, SuiteProfileV2Issue> {
+  return value === null ? success(null) : parseSuiteAvatarRef(value);
+}
+
+function legacyIssue(error: SuiteProfileIssue): Result<never, SuiteProfileV2Issue> {
+  const field = error.field === "application" || error.field === "email"
+    ? "profile"
+    : error.field;
+  return issue(field, error.reason);
+}
+
+/** GitHub uses a bounded URL policy; this does not verify an existing username. */
+export function normalizeSuiteProfileLinkV2(
+  key: unknown,
+  value: unknown,
+): Result<string | null, SuiteProfileV2Issue> {
+  if (typeof key !== "string" || !LINK_KEYS.some((candidate) => candidate === key)) {
+    return issue();
+  }
+  const field = key as SuiteProfileLinkKeyV2;
+  if (value !== null && typeof value !== "string") return issue(field);
+  if (typeof value === "string" && value.length > SUITE_PROFILE_URL_MAX_LENGTH) {
+    return issue(field, "too_long");
+  }
+  if (field === "github") {
+    if (value === null || value === "") return success(null);
+    // Match the original input so URL parsing cannot erase ports, escapes,
+    // dot segments, empty queries, or control characters before validation.
+    if (/[^\x21-\x7e]/u.test(value)) return issue("github");
+    const match = /^https:\/\/(?:www\.)?github\.com\/([A-Za-z0-9_-]{1,100})\/?$/iu.exec(value);
+    return match === null || match[0] !== value
+      ? issue("github")
+      : success(`https://github.com/${match[1]!.toLowerCase()}`);
+  }
+  const parsed = normalizeSuiteProfileLink(field, value);
+  if (!parsed.ok) return legacyIssue(parsed.error);
+  if (parsed.value !== null && parsed.value.length > SUITE_PROFILE_URL_MAX_LENGTH) {
+    return issue(field, "too_long");
+  }
+  return success(parsed.value);
+}
+
+function parsedContent(
+  value: Record<string, unknown>,
+  canonical: boolean,
+): Result<Readonly<{ name: string; bio: string; links: SuiteProfileLinksV2 }>, SuiteProfileV2Issue> {
+  for (const field of ["name", "bio"] as const) {
+    if (typeof value[field] === "string" && value[field].length > MAX_INPUT_TEXT_LENGTH) {
+      return issue(field, "too_long");
+    }
+  }
+  const inputLinks = snapshot(value["links"], LINK_KEYS);
+  if (inputLinks === null) return issue();
+  const links: Record<SuiteProfileLinkKeyV2, string | null> = {
+    bluesky: null, github: null, instagram: null, linkedin: null,
+    telegram: null, website: null, x: null,
+  };
+  for (const key of LINK_KEYS) {
+    const result = normalizeSuiteProfileLinkV2(key, inputLinks[key]);
+    if (!result.ok) return result;
+    if (canonical && result.value !== inputLinks[key]) return issue(key);
+    links[key] = result.value;
+  }
+  // Preserve the released text normalization without widening its six-link schema.
+  const parsed = parseSuiteProfileUpdateRequest({
+    expectedRevision: 0,
+    name: value["name"],
+    bio: value["bio"],
+    links: {
+      bluesky: links.bluesky, instagram: links.instagram, linkedin: links.linkedin,
+      telegram: links.telegram, website: links.website, x: links.x,
+    },
+  });
+  if (!parsed.ok) return legacyIssue(parsed.error);
+  if (canonical && (parsed.value.name !== value["name"] || parsed.value.bio !== value["bio"])) {
+    return issue();
+  }
+  return success({ name: parsed.value.name, bio: parsed.value.bio, links });
+}
+
+function parseView(
+  input: unknown,
+  editor: boolean,
+): Result<SuiteProfileEditorV2 | SuitePublicProfileV2, SuiteProfileV2Issue> {
+  try {
+    const value = snapshot(input, editor ? EDITOR_KEYS : PUBLIC_KEYS);
+    if (value === null) return issue();
+    if (value["schemaVersion"] !== 2) return issue("schemaVersion");
+    const accountId = parseSuiteAccountId(value["accountId"]);
+    if (!accountId.ok) return issue("accountId");
+    const username = editor && value["username"] === null
+      ? success(null)
+      : parseSuiteUsername(value["username"]);
+    if (!username.ok) return issue("username");
+    const revision = value["revision"];
+    if (!nonnegativeInteger(revision) || (!editor && revision === 0)) return issue("revision");
+    const avatarRef = optionalAvatar(value["avatarRef"]);
+    if (!avatarRef.ok) return avatarRef;
+    const publication = value["publication"];
+    if (editor && publication !== "private" && publication !== "published") {
+      return issue("publication");
+    }
+    if (editor && publication === "published" && username.value === null) return issue("username");
+    let content;
+    if (revision === 0) {
+      const links = snapshot(value["links"], LINK_KEYS);
+      if (value["name"] !== "" || value["bio"] !== "" || avatarRef.value !== null
+        || publication !== "private" || links === null
+        || LINK_KEYS.some((key) => links[key] !== null)) return issue();
+      content = {
+        name: "", bio: "",
+        links: { bluesky: null, github: null, instagram: null, linkedin: null,
+          telegram: null, website: null, x: null },
+      };
+    } else {
+      const parsed = parsedContent(value, true);
+      if (!parsed.ok) return parsed;
+      content = parsed.value;
+    }
+    const profile = {
+      schemaVersion: 2 as const,
+      accountId: accountId.value,
+      ...content,
+      avatarRef: avatarRef.value,
+      revision,
+    };
+    if (editor && (publication === "private" || publication === "published")) {
+      return success({ ...profile, username: username.value, publication });
+    }
+    if (username.value === null) return issue("username");
+    return success({ ...profile, username: username.value });
+  } catch {
+    return issue();
+  }
+}
+
+/** Parse a canonical public projection. This does not authenticate its source. */
+export function parseSuitePublicProfileV2(
+  value: unknown,
+): Result<SuitePublicProfileV2, SuiteProfileV2Issue> {
+  const parsed = parseView(value, false);
+  if (!parsed.ok) return parsed;
+  if (parsed.value.username === null || isEditor(parsed.value)) return issue();
+  return success({ ...parsed.value, username: parsed.value.username });
+}
+
+/** Parse a canonical owner view, including the coherent revision-zero default. */
+export function parseSuiteProfileEditorV2(
+  value: unknown,
+): Result<SuiteProfileEditorV2, SuiteProfileV2Issue> {
+  const parsed = parseView(value, true);
+  if (!parsed.ok) return parsed;
+  return isEditor(parsed.value) ? success(parsed.value) : issue();
+}
+
+function isEditor(value: SuiteProfileEditorV2 | SuitePublicProfileV2): value is SuiteProfileEditorV2 {
+  return Object.hasOwn(value, "publication");
+}
+
+/** Normalize an explicit revision-bound edit; the authority applies publication. */
+export function parseSuiteProfileUpdateV2(
+  input: unknown,
+): Result<SuiteProfileUpdateV2, SuiteProfileV2Issue> {
+  try {
+    const value = snapshot(input, UPDATE_KEYS);
+    if (value === null) return issue();
+    if (value["schemaVersion"] !== 2) return issue("schemaVersion");
+    const expectedRevision = value["expectedRevision"];
+    if (!nonnegativeInteger(expectedRevision)) return issue("expectedRevision");
+    const publication = value["publication"];
+    if (publication !== "publish" && publication !== "private") return issue("publication");
+    const avatarRef = optionalAvatar(value["avatarRef"]);
+    if (!avatarRef.ok) return avatarRef;
+    const content = parsedContent(value, false);
+    if (!content.ok) return content;
+    return success({ schemaVersion: 2, expectedRevision, ...content.value,
+      avatarRef: avatarRef.value, publication });
+  } catch {
+    return issue();
+  }
+}
+
+function avatarUrl(ref: unknown, path: string): Result<string, SuiteProfileV2Issue> {
+  const parsed = parseSuiteAvatarRef(ref);
+  return parsed.ok
+    ? success(`${getSuiteAccountsDeployment("production").accountsOrigin}${path}/${parsed.value}.webp`)
+    : parsed;
+}
+
+/** Syntax only; serving requires current publication consent and a live endpoint. */
+export function suiteProfileAvatarPublicUrl(ref: unknown): Result<string, SuiteProfileV2Issue> {
+  return avatarUrl(ref, "/suite/profile/avatar/v1");
+}
+
+/** Syntax only; serving requires the owner's authenticated session and a live endpoint. */
+export function suiteProfileAvatarEditorUrl(ref: unknown): Result<string, SuiteProfileV2Issue> {
+  return avatarUrl(ref, "/api/profile/avatar/v1");
+}