@hraness/suite-accounts 0.9.20

package/src/identity/functions.ts

@@ -0,0 +1,70 @@
+import { makeFunctionReference } from "convex/server";
+import { deepFreeze } from "../immutable.js";
+
+import type { SuitePlanId } from "./catalog.js";
+import type { SuiteInvoiceRef } from "./identifiers.js";
+import type { SuiteReturnTarget } from "./return-targets.js";
+import type { SuiteAccountView } from "./views.js";
+
+export type { SuiteReturnTarget } from "./return-targets.js";
+
+export type StartSuiteCheckoutArgs = {
+  readonly plan: SuitePlanId;
+  readonly returnTarget: SuiteReturnTarget;
+};
+export type StartSuiteCheckoutResult =
+  | { readonly kind: "account" }
+  | { readonly kind: "redirect"; readonly url: string };
+
+export type CreateSuitePortalSessionArgs = {
+  readonly returnTarget: SuiteReturnTarget;
+};
+export type CreateSuitePortalSessionResult = {
+  readonly kind: "redirect";
+  readonly url: string;
+};
+
+export type OpenSuiteInvoiceArgs = {
+  readonly invoiceRef: SuiteInvoiceRef;
+};
+export type OpenSuiteInvoiceResult = {
+  readonly kind: "redirect";
+  readonly url: string;
+};
+
+/** Query the currently authenticated suite account and its safe projections. */
+export const accountsCurrent = makeFunctionReference<
+  "query",
+  Record<never, never>,
+  SuiteAccountView | null
+>("accounts:current");
+
+/** Start hosted Checkout for one exact suite plan. Return URLs are server-owned. */
+export const billingStartCheckout = makeFunctionReference<
+  "action",
+  StartSuiteCheckoutArgs,
+  StartSuiteCheckoutResult
+>("billing:startCheckout");
+
+/** Open the current account's hosted Customer Portal. Its return URL is server-owned. */
+export const billingCreatePortalSession = makeFunctionReference<
+  "action",
+  CreateSuitePortalSessionArgs,
+  CreateSuitePortalSessionResult
+>("billing:createPortalSession");
+
+/** Resolve one owned invoice reference to a validated hosted invoice URL. */
+export const billingOpenInvoice = makeFunctionReference<
+  "action",
+  OpenSuiteInvoiceArgs,
+  OpenSuiteInvoiceResult
+>("billing:openInvoice");
+
+export const suiteAccountsApi = deepFreeze({
+  accounts: { current: accountsCurrent },
+  billing: {
+    createPortalSession: billingCreatePortalSession,
+    openInvoice: billingOpenInvoice,
+    startCheckout: billingStartCheckout,
+  },
+} as const);

package/src/identity/identifiers.ts

@@ -0,0 +1,82 @@
+import { err, ok, type Result } from "@hraness/result";
+
+declare const suiteAccountIdBrand: unique symbol;
+declare const suiteInvoiceRefBrand: unique symbol;
+
+/** An opaque, public account identifier owned by the suite accounts service. */
+export type SuiteAccountId = string & {
+  readonly [suiteAccountIdBrand]: "SuiteAccountId";
+};
+
+/** An opaque, unguessable invoice reference owned by the suite accounts service. */
+export type SuiteInvoiceRef = string & {
+  readonly [suiteInvoiceRefBrand]: "SuiteInvoiceRef";
+};
+
+export type SuiteAccountIdIssue = "invalid-suite-account-id";
+export type SuiteInvoiceRefIssue = "invalid-suite-invoice-ref";
+
+const suiteAccountIdPattern = /^acct_[0-9a-f]{32}$/u;
+const suiteInvoiceRefPattern = /^invref_[0-9a-f]{32}$/u;
+const uuidPattern =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+/** Parse a foreign value into the only supported suite account ID format. */
+export function parseSuiteAccountId(
+  value: unknown,
+): Result<SuiteAccountId, SuiteAccountIdIssue> {
+  return typeof value === "string" && suiteAccountIdPattern.test(value)
+    ? ok(value as SuiteAccountId)
+    : err("invalid-suite-account-id");
+}
+
+/** Parse a foreign value without exposing a provider invoice identifier. */
+export function parseSuiteInvoiceRef(
+  value: unknown,
+): Result<SuiteInvoiceRef, SuiteInvoiceRefIssue> {
+  return typeof value === "string" && suiteInvoiceRefPattern.test(value)
+    ? ok(value as SuiteInvoiceRef)
+    : err("invalid-suite-invoice-ref");
+}
+
+/**
+ * Generate a suite account ID from a cryptographically random UUID.
+ *
+ * The injected seam lets deterministic tests prove formatting. Production callers
+ * should keep the default Web Crypto implementation.
+ */
+export function generateSuiteAccountId(
+  randomUuid: () => string = () => crypto.randomUUID(),
+): SuiteAccountId {
+  const uuid = randomUuid();
+  if (!uuidPattern.test(uuid)) {
+    throw new TypeError("The suite account ID source did not return a UUID.");
+  }
+  const candidate = `acct_${uuid.replaceAll("-", "").toLowerCase()}`;
+  const parsed = parseSuiteAccountId(candidate);
+  if (!parsed.ok) {
+    throw new TypeError("The suite account ID source produced an invalid value.");
+  }
+  return parsed.value;
+}
+
+/**
+ * Generate a provider-neutral invoice reference from cryptographic randomness.
+ *
+ * The reference is safe to project to a browser only after the accounts service
+ * associates it with an invoice and resolves it under the authenticated account.
+ */
+export function generateSuiteInvoiceRef(
+  randomUuid: () => string = () => crypto.randomUUID(),
+): SuiteInvoiceRef {
+  const uuid = randomUuid();
+  if (!uuidPattern.test(uuid)) {
+    throw new TypeError("The suite invoice reference source did not return a UUID.");
+  }
+  const candidate = `invref_${uuid.replaceAll("-", "").toLowerCase()}`;
+  const parsed = parseSuiteInvoiceRef(candidate);
+  if (!parsed.ok) {
+    throw new TypeError("The suite invoice reference source produced an invalid value.");
+  }
+  return parsed.value;
+}

package/src/identity/index.ts

@@ -0,0 +1,10 @@
+export * from "./catalog.js";
+export * from "./consumers.js";
+export * from "./identifiers.js";
+export * from "./links.js";
+export * from "./membership.js";
+export * from "./principals.js";
+export * from "./profiles.js";
+export * from "./profiles-v2.js";
+export * from "./usernames.js";
+export * from "./views.js";

package/src/identity/links.ts

@@ -0,0 +1,280 @@
+import { ok, type Result } from "@hraness/result";
+import { deepFreeze } from "../immutable.js";
+
+import {
+  grantedSuiteFeatureSets,
+  parseSuiteCatalogRevision,
+  parseSuiteFeatureId,
+  SUITE_FEATURE_IDS,
+  type SuiteCatalogRevision,
+  type SuiteFeatureId,
+} from "./catalog.js";
+import { parseSuiteAccountId, type SuiteAccountId } from "./identifiers.js";
+import {
+  parseIdentitySubject,
+  parseSuiteEnvironment,
+  parseSuiteProduct,
+  type LegacySuiteProductId,
+  type SuiteEnvironment,
+  type SuiteProduct,
+} from "./principals.js";
+
+export const IDENTITY_LINK_PROOF_VERSION =
+  "suite-product-link-proof-v1" as const;
+export const IDENTITY_LINK_RECEIPT_VERSION =
+  "suite-link-receipt-v1" as const;
+export const SUITE_ENTITLEMENTS_CLAIM_VERSION =
+  "suite-entitlements-v1" as const;
+export const SUITE_ENTITLEMENT_RECEIPT_VERSION =
+  "suite-entitlement-receipt-v1" as const;
+export const IDENTITY_LINK_MAX_TTL_MS = 5 * 60_000;
+export const SUITE_ENTITLEMENT_RECEIPT_MAX_TTL_MS = 5 * 60_000;
+export const IDENTITY_LINK_CLOCK_SKEW_MS = 30_000;
+
+export const SUITE_LINK_PRODUCTS = deepFreeze([
+  "soundfish",
+  "hra",
+  "peopleblade",
+  "ghostget",
+  // Compatibility-only readers for already-issued publication receipts and links.
+  "crclte",
+  "pub",
+] as const satisfies readonly SuiteProduct[]);
+export const LEGACY_SUITE_LINK_PRODUCTS = deepFreeze([
+  "oprte",
+  "kitchen",
+] as const satisfies readonly LegacySuiteProductId[]);
+
+export type SuiteLinkProduct = (typeof SUITE_LINK_PRODUCTS)[number];
+export type LegacySuiteLinkProduct =
+  (typeof LEGACY_SUITE_LINK_PRODUCTS)[number];
+export type SignedSuiteLinkProduct =
+  | LegacySuiteLinkProduct
+  | SuiteLinkProduct;
+
+export function parseSuiteLinkProduct(
+  value: unknown,
+): Result<SuiteLinkProduct, "invalid-product"> {
+  const parsed = parseSuiteProduct(value);
+  if (!parsed.ok) return parsed;
+  switch (parsed.value) {
+    case "soundfish":
+    case "hra":
+    case "peopleblade":
+    case "ghostget":
+    case "crclte":
+    case "pub":
+      return ok(parsed.value);
+  }
+}
+
+export type ProductLinkProof = Readonly<{
+  challengeId: string;
+  environment: SuiteEnvironment;
+  expiresAtMs: number;
+  issuedAtMs: number;
+  keyVersion: string;
+  localSubject: string;
+  product: SignedSuiteLinkProduct;
+}>;
+
+export type SuiteLinkReceiptPayload = ProductLinkProof & Readonly<{
+  suiteAccountId: SuiteAccountId | string;
+}>;
+
+export type SuiteLinkReceipt = SuiteLinkReceiptPayload & Readonly<{
+  signature: string;
+  version: typeof IDENTITY_LINK_RECEIPT_VERSION;
+}>;
+
+export type SuiteEntitlementsClaim = Readonly<{
+  catalogRevision: SuiteCatalogRevision;
+  expiresAtMs: number;
+  features: readonly SuiteFeatureId[];
+  observedAtMs: number;
+  projectionRevision: number;
+  version: typeof SUITE_ENTITLEMENTS_CLAIM_VERSION;
+}>;
+
+export type SuiteEntitlementReceiptPayload = Readonly<{
+  entitlements: SuiteEntitlementsClaim;
+  environment: SuiteEnvironment;
+  expiresAtMs: number;
+  issuedAtMs: number;
+  keyVersion: string;
+  product: SignedSuiteLinkProduct;
+  suiteAccountId: SuiteAccountId | string;
+}>;
+
+export type SuiteEntitlementReceipt =
+  SuiteEntitlementReceiptPayload & Readonly<{
+    signature: string;
+    version: typeof SUITE_ENTITLEMENT_RECEIPT_VERSION;
+  }>;
+
+export type IdentityLinkInputIssue =
+  | "expired"
+  | "invalid"
+  | "not-yet-valid";
+
+function safeInteger(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+export function validateProductLinkProof(
+  input: ProductLinkProof,
+  now: number,
+): IdentityLinkInputIssue | null {
+  const product = parseSuiteLinkProduct(input.product);
+  const environment = parseSuiteEnvironment(input.environment);
+  const localSubject = parseIdentitySubject(input.localSubject);
+  if (
+    !safeInteger(now)
+    || !product.ok
+    || !environment.ok
+    || !localSubject.ok
+    || !/^[A-Za-z0-9_-]{22,128}$/u.test(input.challengeId)
+    || !/^[a-z0-9][a-z0-9._-]{0,31}$/u.test(input.keyVersion)
+    || !safeInteger(input.issuedAtMs)
+    || !safeInteger(input.expiresAtMs)
+    || input.expiresAtMs <= input.issuedAtMs
+    || input.expiresAtMs - input.issuedAtMs > IDENTITY_LINK_MAX_TTL_MS
+  ) {
+    return "invalid";
+  }
+  if (input.issuedAtMs > now + IDENTITY_LINK_CLOCK_SKEW_MS) {
+    return "not-yet-valid";
+  }
+  return input.expiresAtMs <= now ? "expired" : null;
+}
+
+export function productLinkProofMessage(input: ProductLinkProof): string {
+  return JSON.stringify([
+    IDENTITY_LINK_PROOF_VERSION,
+    input.product,
+    input.environment,
+    input.localSubject,
+    input.challengeId,
+    input.issuedAtMs,
+    input.expiresAtMs,
+    input.keyVersion,
+  ]);
+}
+
+export function suiteLinkReceiptMessage(
+  input: SuiteLinkReceiptPayload,
+): string {
+  return JSON.stringify([
+    IDENTITY_LINK_RECEIPT_VERSION,
+    input.product,
+    input.environment,
+    input.localSubject,
+    input.suiteAccountId,
+    input.challengeId,
+    input.issuedAtMs,
+    input.expiresAtMs,
+    input.keyVersion,
+  ]);
+}
+
+export function validateSuiteLinkReceipt(
+  input: SuiteLinkReceipt,
+  now: number,
+): IdentityLinkInputIssue | null {
+  const proofIssue = validateProductLinkProof(input, now);
+  if (
+    proofIssue !== null
+    || input.version !== IDENTITY_LINK_RECEIPT_VERSION
+    || !parseSuiteAccountId(input.suiteAccountId).ok
+    || !/^[A-Za-z0-9_-]{43}$/u.test(input.signature)
+  ) {
+    return proofIssue ?? "invalid";
+  }
+  return null;
+}
+
+function exactGrantedFeatures(
+  revision: SuiteCatalogRevision,
+  values: readonly SuiteFeatureId[],
+): boolean {
+  if (values.length > SUITE_FEATURE_IDS.length) return false;
+  const parsed: SuiteFeatureId[] = [];
+  for (const value of values) {
+    const feature = parseSuiteFeatureId(value);
+    if (!feature.ok || parsed.includes(feature.value)) return false;
+    parsed.push(feature.value);
+  }
+  return grantedSuiteFeatureSets(revision).some(set =>
+    set.length === parsed.length
+    && set.every((feature, index) => feature === parsed[index])
+  );
+}
+
+export function validateSuiteEntitlementsClaim(
+  input: SuiteEntitlementsClaim,
+): boolean {
+  const catalogRevision = parseSuiteCatalogRevision(input.catalogRevision);
+  return (
+    input.version === SUITE_ENTITLEMENTS_CLAIM_VERSION
+    && catalogRevision.ok
+    && safeInteger(input.observedAtMs)
+    && safeInteger(input.expiresAtMs)
+    && input.expiresAtMs > input.observedAtMs
+    && safeInteger(input.projectionRevision)
+    && Array.isArray(input.features)
+    && exactGrantedFeatures(catalogRevision.value, input.features)
+  );
+}
+
+export function suiteEntitlementReceiptMessage(
+  input: SuiteEntitlementReceiptPayload,
+): string {
+  return JSON.stringify([
+    SUITE_ENTITLEMENT_RECEIPT_VERSION,
+    input.product,
+    input.environment,
+    input.suiteAccountId,
+    input.keyVersion,
+    input.issuedAtMs,
+    input.expiresAtMs,
+    input.entitlements.version,
+    input.entitlements.catalogRevision,
+    input.entitlements.observedAtMs,
+    input.entitlements.expiresAtMs,
+    input.entitlements.projectionRevision,
+    input.entitlements.features,
+  ]);
+}
+
+export function validateSuiteEntitlementReceipt(
+  input: SuiteEntitlementReceipt,
+  now: number,
+): IdentityLinkInputIssue | null {
+  const product = parseSuiteLinkProduct(input.product);
+  const environment = parseSuiteEnvironment(input.environment);
+  if (
+    !safeInteger(now)
+    || input.version !== SUITE_ENTITLEMENT_RECEIPT_VERSION
+    || !product.ok
+    || !environment.ok
+    || !parseSuiteAccountId(input.suiteAccountId).ok
+    || !/^[a-z0-9][a-z0-9._-]{0,31}$/u.test(input.keyVersion)
+    || !safeInteger(input.issuedAtMs)
+    || !safeInteger(input.expiresAtMs)
+    || input.expiresAtMs <= input.issuedAtMs
+    || input.expiresAtMs - input.issuedAtMs
+      > SUITE_ENTITLEMENT_RECEIPT_MAX_TTL_MS
+    || !validateSuiteEntitlementsClaim(input.entitlements)
+    || input.expiresAtMs > input.entitlements.expiresAtMs
+    || !/^[A-Za-z0-9_-]{43}$/u.test(input.signature)
+  ) {
+    return "invalid";
+  }
+  if (
+    input.issuedAtMs > now + IDENTITY_LINK_CLOCK_SKEW_MS
+    || input.entitlements.observedAtMs > now + IDENTITY_LINK_CLOCK_SKEW_MS
+  ) {
+    return "not-yet-valid";
+  }
+  return input.expiresAtMs <= now ? "expired" : null;
+}

package/src/identity/membership.ts

@@ -0,0 +1,156 @@
+import { deepFreeze } from "../immutable.js";
+
+/**
+ * Public membership product shown on the shared subscription surfaces.
+ *
+ * Only display metadata lives here: the stable product ID, emoji, name,
+ * canonical link, and short description. Accounts and the hraness.com plan
+ * page render the list verbatim; the portfolio site keeps it convergent with
+ * the authored portfolio catalog.
+ */
+export type SuiteMembershipProduct = Readonly<{
+  description: string;
+  emoji: string;
+  href: `https://${string}`;
+  id: string;
+  name: string;
+}>;
+
+export const SUITE_MEMBERSHIP_PRODUCTS = deepFreeze([
+  {
+    description: "model benchmark scores plotted against cost and tokens per task",
+    emoji: "📈",
+    href: "https://aicharts.io",
+    id: "aicharts",
+    name: "AI CHARTS",
+  },
+  {
+    description: "markdown knowledge base that gives agents the decisions behind code",
+    emoji: "📝",
+    href: "https://wordcell.io",
+    id: "kb",
+    name: "WORDCELL",
+  },
+  {
+    description: "memory for agents that stores each fact with its sources and history",
+    emoji: "📚",
+    href: "https://oh.computer",
+    id: "oh-computer",
+    name: "OH",
+  },
+  {
+    description: "private library for what you read, with notes your agent can cite",
+    emoji: "🧽",
+    href: "https://sponge.computer",
+    id: "sponge",
+    name: "SPONGE",
+  },
+  {
+    description: "local personal crm for everyone you know, built for your agent",
+    emoji: "📇",
+    href: "https://peopleblade.com",
+    id: "peopleblade",
+    name: "PEOPLEBLADE",
+  },
+  {
+    description: "named web actions for ai agents: read pages, save media, use connected accounts",
+    emoji: "👻",
+    href: "https://ghostget.com",
+    id: "ghostget",
+    name: "GHOSTGET",
+  },
+  {
+    description: "free agent skill that writes dated dossiers on people, sources cited",
+    emoji: "🦾",
+    href: "https://soulscrape.com",
+    id: "soulscrape",
+    name: "SOULSCRAPE",
+  },
+  {
+    description: "media studio for agents: images, 3d, animation, and video to revise",
+    emoji: "📸",
+    href: "https://slopcamera.com",
+    id: "slopcamera",
+    name: "SLOPCAMERA",
+  },
+  {
+    description: "build prompt that turns a coding agent into a trading-system designer",
+    emoji: "📈",
+    href: "https://sloptrade.com",
+    id: "sloptrade",
+    name: "SLOPTRADE",
+  },
+  {
+    description: "software studio making tools for ai agents and for people",
+    emoji: "🪢",
+    href: "https://hraness.com",
+    id: "hraness",
+    name: "HRANESS",
+  },
+  {
+    description: "free sleep sounds made in your browser, with sourced sleep guides",
+    emoji: "💤",
+    href: "https://sleepy.land",
+    id: "sleepyland",
+    name: "SLEEPYLAND",
+  },
+  {
+    description: "independent history of stripe where every event is dated and sourced",
+    emoji: "🦓",
+    href: "https://hraness.com/stripe",
+    id: "stripe-history",
+    name: "STRIPE HISTORY",
+  },
+  {
+    description: "ehlers-danlos evidence stratified by kind, every record linked to sources",
+    emoji: "🧬",
+    href: "https://hraness.com/eds",
+    id: "eds-research",
+    name: "EDS RESEARCH INDEX",
+  },
+  {
+    description: "estimate act 60 savings after real costs, with sourced guides and a day tracker",
+    emoji: "⏱️",
+    href: "https://act60.me",
+    id: "act60",
+    name: "ACT60",
+  },
+  {
+    description: "browser experiments for a game of algorithmic organisms",
+    emoji: "🦠",
+    href: "https://platonik.space",
+    id: "platonik",
+    name: "PLATONIK",
+  },
+  {
+    description: "repeatable app states for browser agents, opened by url",
+    emoji: "🎯",
+    href: "https://hraness.com/direct",
+    id: "direct",
+    name: "DIRECT",
+  },
+  {
+    description: "fresh puzzles for ai agents, scored exactly, with a signed receipt",
+    emoji: "📡",
+    href: "https://clankdar.com",
+    id: "clankdar",
+    name: "CLANKDAR",
+  },
+  {
+    description: "turn the chapters of your life into one timeline you can share",
+    emoji: "📊",
+    href: "https://lifecharts.io",
+    id: "lifedaysleft",
+    name: "LIFECHARTS",
+  },
+  {
+    description: "free publication about how companies put ai agents to work",
+    emoji: "🏭",
+    href: "https://swft.io",
+    id: "swft",
+    name: "SWFT",
+  },
+] as const satisfies readonly SuiteMembershipProduct[]);
+
+export type SuiteMembershipProductId =
+  (typeof SUITE_MEMBERSHIP_PRODUCTS)[number]["id"];