@hraness/suite-accounts 0.9.20

package/src/identity/views.ts

@@ -0,0 +1,289 @@
+import { err, isRecord, ok, type Result } from "@hraness/result";
+import { deepFreeze } from "../immutable.js";
+
+import {
+  featuresForSuitePlan,
+  parseAnySuitePlanId,
+  parseSuiteCatalogRevision,
+  parseSuiteFeatureId,
+  parseSuitePlanId,
+  SUITE_CATALOG_REVISION,
+  SUITE_FEATURE_IDS,
+  type AnySuitePlanId,
+  type CurrentSuiteCatalogRevision,
+  type SuiteCatalogRevision,
+  type SuiteFeatureId,
+} from "./catalog.js";
+import {
+  parseSuiteAccountId,
+  parseSuiteInvoiceRef,
+  type SuiteAccountId,
+  type SuiteInvoiceRef,
+} from "./identifiers.js";
+import {
+  parseSuiteUsername,
+  type SuiteUsername,
+} from "./usernames.js";
+
+export const SUITE_SUBSCRIPTION_STATUSES = deepFreeze([
+  "incomplete",
+  "trialing",
+  "active",
+  "past_due",
+  "paused",
+  "canceled",
+  "unpaid",
+] as const);
+export const SUITE_INVOICE_STATUSES = deepFreeze([
+  "draft",
+  "open",
+  "paid",
+  "void",
+  "uncollectible",
+] as const);
+
+export type SuiteSubscriptionStatus =
+  (typeof SUITE_SUBSCRIPTION_STATUSES)[number];
+export type SuiteInvoiceStatus = (typeof SUITE_INVOICE_STATUSES)[number];
+
+export type SuiteSubscriptionView = {
+  readonly cancelAtPeriodEnd: boolean;
+  readonly catalogRevision: SuiteCatalogRevision;
+  readonly currentPeriodEndMs: number | null;
+  readonly plan: AnySuitePlanId;
+  readonly status: SuiteSubscriptionStatus;
+};
+
+export type SuiteInvoiceView = {
+  readonly amountDueCents: number;
+  readonly amountPaidCents: number;
+  readonly createdAtMs: number;
+  readonly currency: "usd";
+  readonly invoiceRef: SuiteInvoiceRef | null;
+  readonly number: string | null;
+  readonly status: SuiteInvoiceStatus;
+};
+
+export type SuiteAccountView = {
+  readonly accountId: SuiteAccountId;
+  readonly catalogRevision: CurrentSuiteCatalogRevision;
+  readonly email: string;
+  readonly features: SuiteFeatureId[];
+  readonly invoices: SuiteInvoiceView[];
+  readonly name: string | null;
+  readonly plan: AnySuitePlanId | null;
+  readonly subscription: SuiteSubscriptionView | null;
+  readonly username: SuiteUsername | null;
+};
+
+export type SuiteViewIssue =
+  | "invalid-account-view"
+  | "invalid-invoice-view"
+  | "invalid-subscription-view";
+
+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;
+}
+
+function parseEmail(value: unknown): string | null {
+  return typeof value === "string" &&
+      value.length <= 320 &&
+      /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(value)
+    ? value
+    : null;
+}
+
+function parseOptionalName(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  return typeof value === "string" &&
+      value.length >= 1 &&
+      value.length <= 160 &&
+      value.trim() === value &&
+      !containsAsciiControl(value)
+    ? value
+    : undefined;
+}
+
+function parseNonnegativeInteger(value: unknown): number | null {
+  return typeof value === "number" &&
+      Number.isSafeInteger(value) &&
+      value >= 0
+    ? value
+    : null;
+}
+
+function parseOptionalTimestamp(value: unknown): number | null | undefined {
+  if (value === null) return null;
+  return parseNonnegativeInteger(value) ?? undefined;
+}
+
+function isOneOf<const Values extends readonly string[]>(
+  values: Values,
+  value: unknown,
+): value is Values[number] {
+  return typeof value === "string" &&
+    (values as readonly string[]).includes(value);
+}
+
+export function parseSuiteSubscriptionView(
+  value: unknown,
+): Result<SuiteSubscriptionView, "invalid-subscription-view"> {
+  if (!isRecord(value)) return err("invalid-subscription-view");
+  const catalogRevision = parseSuiteCatalogRevision(value["catalogRevision"]);
+  const plan = catalogRevision.ok
+    ? parseSuitePlanId(value["plan"], catalogRevision.value)
+    : catalogRevision;
+  const currentPeriodEndMs = parseOptionalTimestamp(value["currentPeriodEndMs"]);
+  if (
+    !plan.ok ||
+    !catalogRevision.ok ||
+    !isOneOf(SUITE_SUBSCRIPTION_STATUSES, value["status"]) ||
+    typeof value["cancelAtPeriodEnd"] !== "boolean" ||
+    currentPeriodEndMs === undefined
+  ) {
+    return err("invalid-subscription-view");
+  }
+  return ok({
+    cancelAtPeriodEnd: value["cancelAtPeriodEnd"],
+    catalogRevision: catalogRevision.value,
+    currentPeriodEndMs,
+    plan: plan.value,
+    status: value["status"],
+  });
+}
+
+export function parseSuiteInvoiceView(
+  value: unknown,
+): Result<SuiteInvoiceView, "invalid-invoice-view"> {
+  if (
+    !isRecord(value) ||
+    !isOneOf(SUITE_INVOICE_STATUSES, value["status"]) ||
+    value["currency"] !== "usd"
+  ) {
+    return err("invalid-invoice-view");
+  }
+  const amountDueCents = parseNonnegativeInteger(value["amountDueCents"]);
+  const amountPaidCents = parseNonnegativeInteger(value["amountPaidCents"]);
+  const createdAtMs = parseNonnegativeInteger(value["createdAtMs"]);
+  const number =
+    value["number"] === null
+      ? null
+      : typeof value["number"] === "string" &&
+          value["number"].length >= 1 &&
+          value["number"].length <= 80 &&
+          value["number"].trim() === value["number"]
+        ? value["number"]
+        : undefined;
+  const invoiceRef =
+    value["invoiceRef"] === null
+      ? ok(null)
+      : parseSuiteInvoiceRef(value["invoiceRef"]);
+  if (
+    amountDueCents === null ||
+    amountPaidCents === null ||
+    createdAtMs === null ||
+    number === undefined ||
+    !invoiceRef.ok
+  ) {
+    return err("invalid-invoice-view");
+  }
+  return ok({
+    amountDueCents,
+    amountPaidCents,
+    createdAtMs,
+    currency: "usd",
+    invoiceRef: invoiceRef.value,
+    number,
+    status: value["status"],
+  });
+}
+
+function parseFeatures(value: unknown): SuiteFeatureId[] | null {
+  if (!Array.isArray(value) || value.length > SUITE_FEATURE_IDS.length) {
+    return null;
+  }
+  const parsed: SuiteFeatureId[] = [];
+  for (const entry of value) {
+    const feature = parseSuiteFeatureId(entry);
+    if (!feature.ok || parsed.includes(feature.value)) return null;
+    parsed.push(feature.value);
+  }
+  return parsed;
+}
+
+export function parseSuiteAccountView(
+  value: unknown,
+): Result<SuiteAccountView, "invalid-account-view"> {
+  if (!isRecord(value)) return err("invalid-account-view");
+  const accountId = parseSuiteAccountId(value["accountId"]);
+  const email = parseEmail(value["email"]);
+  const name = parseOptionalName(value["name"]);
+  const username = value["username"] === null || value["username"] === undefined
+    ? ok(null)
+    : parseSuiteUsername(value["username"]);
+  const subscription =
+    value["subscription"] === null
+      ? ok(null)
+      : parseSuiteSubscriptionView(value["subscription"]);
+  const plan =
+    value["plan"] === null ? ok(null) : parseAnySuitePlanId(value["plan"]);
+  const features = parseFeatures(value["features"]);
+  if (
+    !accountId.ok ||
+    value["catalogRevision"] !== SUITE_CATALOG_REVISION ||
+    email === null ||
+    name === undefined ||
+    !username.ok ||
+    !subscription.ok ||
+    !plan.ok ||
+    features === null ||
+    !Array.isArray(value["invoices"]) ||
+    value["invoices"].length > 100 ||
+    plan.value !== (subscription.value?.plan ?? null)
+  ) {
+    return err("invalid-account-view");
+  }
+  const statusCanGrant =
+    subscription.value !== null &&
+    (subscription.value.status === "active" ||
+      subscription.value.status === "trialing");
+  const planFeatures =
+    subscription.value === null
+      ? []
+      : featuresForSuitePlan(
+          subscription.value.plan,
+          subscription.value.catalogRevision,
+        );
+  const exactPositiveGrant =
+    statusCanGrant &&
+    features.length === planFeatures.length &&
+    features.every((feature, index) => feature === planFeatures[index]);
+  // A backend may remove an otherwise eligible grant at an additional
+  // fail-closed boundary such as current-period expiry. Positive grants still
+  // have to match the checked catalog exactly; only the empty projection is a
+  // valid conservative subset.
+  if (features.length > 0 && !exactPositiveGrant) {
+    return err("invalid-account-view");
+  }
+  const invoices: SuiteInvoiceView[] = [];
+  for (const entry of value["invoices"]) {
+    const invoice = parseSuiteInvoiceView(entry);
+    if (!invoice.ok) return err("invalid-account-view");
+    invoices.push(invoice.value);
+  }
+  return ok({
+    accountId: accountId.value,
+    catalogRevision: SUITE_CATALOG_REVISION,
+    email,
+    features,
+    invoices,
+    name,
+    plan: plan.value,
+    subscription: subscription.value,
+    username: username.value,
+  });
+}

package/src/immutable.ts

@@ -0,0 +1,25 @@
+/**
+ * Freeze an owned JSON-like value recursively before it crosses a public
+ * security boundary. This helper intentionally does not traverse functions or
+ * collection classes. Registry and configuration values use only plain
+ * records and arrays.
+ */
+export function deepFreeze<const Value>(value: Value): Value {
+  const visited = new WeakSet<object>();
+
+  function freezeOwned(current: unknown): void {
+    if (current === null || typeof current !== "object") return;
+    if (visited.has(current)) return;
+    visited.add(current);
+    for (const key of Reflect.ownKeys(current)) {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key);
+      if (descriptor !== undefined && "value" in descriptor) {
+        freezeOwned(descriptor.value);
+      }
+    }
+    Object.freeze(current);
+  }
+
+  freezeOwned(value);
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./client-configuration.js";
+export * from "./convex-browser-auth.js";
+export * from "./oidc-device-code.js";
+export * from "./oidc-session-policy.js";
+export * from "./public-config.js";
+export * from "./registry.js";
+export * from "./urls.js";

package/src/oidc-continuation.ts

@@ -0,0 +1,59 @@
+function htmlAttribute(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll('"', """)
+    .replaceAll("'", "'")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function inlineJson(value: string): string {
+  return JSON.stringify(value)
+    .replaceAll("&", "\\u0026")
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029");
+}
+
+export const SUITE_OIDC_JUST_SIGNED_IN_STORAGE_KEY =
+  "hraness:suite:signed-in:v1" as const;
+
+export function createOidcContinuationResponse(
+  returnTo: string,
+  nonce: string,
+  cookies: readonly string[],
+): Response {
+  const headers = new Headers({
+    "cache-control": "no-store",
+    "content-security-policy": [
+      "default-src 'none'",
+      "base-uri 'none'",
+      "form-action 'none'",
+      "frame-ancestors 'none'",
+      `script-src 'nonce-${nonce}'`,
+    ].join("; "),
+    "content-type": "text/html; charset=utf-8",
+    pragma: "no-cache",
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+    "x-frame-options": "DENY",
+  });
+  for (const cookie of cookies) headers.append("set-cookie", cookie);
+  const body = [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    "<title>Signed in</title>",
+    "</head>",
+    "<body>",
+    "<p>Signed in.</p>",
+    `<p><a href="${htmlAttribute(returnTo)}">Continue</a></p>`,
+    `<script nonce="${nonce}">try{sessionStorage.setItem(${inlineJson(SUITE_OIDC_JUST_SIGNED_IN_STORAGE_KEY)},"1")}catch{}location.replace(${inlineJson(returnTo)});</script>`,
+    "</body>",
+    "</html>",
+  ].join("");
+  return new Response(body, { headers, status: 200 });
+}