@arcblock/did-connect-service 4.1.40 → 4.1.42

package/dist/_generated/asset-manifest.js

@@ -6,7 +6,7 @@ export default {
   "header.js": "header.8703ab26.js",
   "login.css": "login.fa75e481.css",
   "design.css": "design.99dc4ddc.css",
-  "admin.css": "admin.ab0009f2.css",
+  "admin.css": "admin.d99b416e.css",
   "admin-core.js": "admin-core.d42d34ce.js",
-  "admin-extra.js": "admin-extra.c7a0720f.js"
+  "admin-extra.js": "admin-extra.da2c9785.js"
 };

package/dist/app-identity.d.ts

@@ -0,0 +1,283 @@
+/**
+ * App identity — the single resolver for "what is this app called and what does it
+ * look like" (did#247, S4 of ArcBlock/arc#7073).
+ *
+ * Every surface that shows the app's identity (name / description / icon / logos /
+ * theme) resolves it here instead of reading D1 and layering fallbacks on its own:
+ * `resolveAppInfo`, `BrandingHandler` (logo serving, letter-mark fallback, theme CSS,
+ * OG text), `BlockletJsHandler` (`__blocklet__.js`), the login page, the homepage and
+ * the access-key page name.
+ *
+ * Layers, highest first:
+ *
+ *   name         instance app:branding.name → instance legacy app:name → package name
+ *                → deployment name → built-in default
+ *   description  instance app:branding.description (any string, "" included)
+ *                → package description → absent
+ *   icon         instance app:branding.icon
+ *   logos        instance app:logos.<slot> (R2 key) → package logo (square slot, `v` only;
+ *                every type whose fallback chain reaches `square` follows it)
+ *                → fallback-scope app:logos.<slot>
+ *   theme        instance app:theme → package palette → fallback-scope app:theme → default;
+ *                each deep-merged over the built-in palettes by formatThemeForOutput
+ *   passportColor instance app:branding.passportColor → package passportColor
+ *                → fallback-scope app:branding.passportColor → absent
+ *
+ * connect-service never reads the app package itself (arc#7073 red line 1): the
+ * package layer only ever arrives as host-supplied {@link PackageBranding}, and it is
+ * never written back into D1 (red line 2).
+ *
+ * ## Per-field origin
+ *
+ * Every field carries `from`. `"instance"` means the value is configured on the
+ * instance whose identity is being resolved — nothing else. When the host asserted a
+ * request's instance X (route-context `instanceDid`, or an opted-in `X-Instance-Did`)
+ * but a surface read another scope's rows (e.g. `__blocklet__.js` reading the
+ * handler's construction instance), those rows are passed with `scope: "fallback"`
+ * and labelled `"deployment"` — see {@link identityScopeFor}. The arc-side lesson
+ * recorded on `resolveRawInstanceBranding` (services/shared/src/identity.ts) is that a
+ * ROOT fallback masquerading as instance-configured branding permanently outranks the
+ * package layer. With no asserted instance (a root / control-plane request), the
+ * construction rows ARE the instance's own and are labelled `"instance"`.
+ *
+ * ## Precedence decision (S5): own instance > package > fallback > default
+ *
+ * For the layers S5/S8 add — logos, theme, passportColor — a fallback-scope row (the
+ * deployment's root instance standing in for an app that has no row of its own) ranks
+ * BELOW the package layer. A stand-in row describes a different app; the package is the
+ * app's own declaration, so it must win (this is the arc-side lesson above). Only the
+ * app's OWN instance rows outrank the package (R3: the operator's override wins, and
+ * clearing it falls back to the package).
+ *
+ *   - Logos are resolved per slot: own slot > package slot > fallback slot. The package
+ *     fills only `square`, so a fallback `rect` / `favicon` / splash row is still used
+ *     for its own slot; variant/chain semantics on derived surfaces belong to S7.
+ *   - Theme is one unit: an own configured theme replaces the package palette entirely
+ *     (no merging of the two); a fallback theme is used only when the package has none.
+ *   - The package layer never changes output where it is absent: without a package
+ *     logo/theme/passportColor every surface is byte-identical to S4 (baseline).
+ *
+ * name / description KEEP S4's order (fallback rows > package): changing it would change
+ * existing output on configured deployments, which S5 does not do. Aligning them is a
+ * separate, explicit decision.
+ *
+ * ## Which layers a surface honors is the caller's input, not a flag
+ *
+ * The surfaces do not all honor the same layers today, and S4 preserves that byte for
+ * byte (locked by test/app-identity-baseline.test.ts). The resolver is pure and takes
+ * only the layers it is given, so each divergence is expressed by what the caller
+ * passes:
+ *
+ *   - Letter-mark logo fallback: passes only the instance `branding` row and the
+ *     deployment name — legacy app:name and package branding never reach the initial.
+ *   - Embedded (Node) host: builds its handler identity with no instance rows at all,
+ *     so legacy app:name is never honored there (per-request surfaces still overlay
+ *     the request-scope app:branding).
+ *   - Per-request surfaces pass the handler's build-time identity as `inherited`: the
+ *     request-scope instance rows sit on top of it, and it replaces the
+ *     package / deployment / default layers for name and description.
+ *   - The scope (which instance's rows are read) stays where it is today at each call
+ *     site; see `readInstanceIdentityRows`.
+ *   - The package logo / palette / passportColor (S5, S8) enter once, in the build-time
+ *     identity, and reach per-request surfaces through `inherited`, ranked as described
+ *     under "Precedence decision" below.
+ */
+import { type AppInfo, type PackageBranding } from "./package-branding.js";
+export type Origin = "instance" | "package" | "deployment" | "default";
+/** Logo slots (`app:logos.<type>` = R2 key on the instance layer). */
+export declare const LOGO_TYPES: readonly ["square", "squareDark", "rect", "rectDark", "favicon", "splashPortrait", "splashLandscape", "ogImage"];
+export type LogoType = (typeof LOGO_TYPES)[number];
+/**
+ * The D1 settings keys that carry app identity. Every identity SURFACE reads them through
+ * `readInstanceIdentityRows` / `instanceIdentityRowsFromSettings`. Raw reads remain in the
+ * admin CRUD endpoints, instance listings and federation/invite paths (see the did#253
+ * PR's unconverged-readers table).
+ */
+export declare const IDENTITY_SETTING_KEYS: {
+    readonly branding: "app:branding";
+    readonly legacyName: "app:name";
+    readonly logos: "app:logos";
+    readonly theme: "app:theme";
+};
+export type IdentityRowField = keyof typeof IDENTITY_SETTING_KEYS;
+/**
+ * Raw identity rows of one instance, as stored. A field that is `null`/`undefined`
+ * is "not configured" (or not read by this caller).
+ */
+export interface InstanceIdentityRows {
+    branding?: string | null;
+    legacyName?: string | null;
+    logos?: string | null;
+    theme?: string | null;
+    /**
+     * `"own"` (default): the rows belong to the instance being resolved.
+     * `"fallback"`: the caller read a stand-in scope (the deployment's root instance)
+     * because it cannot scope to the requesting instance — values are used unchanged
+     * but labelled `"deployment"`, never `"instance"`.
+     */
+    scope?: "own" | "fallback";
+}
+export interface AppIdentityInput {
+    instance?: InstanceIdentityRows;
+    /**
+     * An identity already resolved for this app (the handler's build-time identity).
+     * When given, it replaces the package / deployment / default layers for name and
+     * description — including an empty inherited name — and keeps its own origins. Its
+     * logos / blurhash / theme fill whatever the request-scope rows do not configure.
+     */
+    inherited?: AppIdentity;
+    /** Host-supplied package branding. Ignored when `inherited` is given. */
+    packageBranding?: PackageBranding;
+    /** Deployment-global name (`CONNECT_APP_NAME` / embedded `appName`). `""` counts as set. */
+    deploymentName?: string;
+    /** Built-in last resort for the name. Default `"DID Connect"`. */
+    defaultName?: string;
+}
+export interface AppIdentity {
+    v: 1;
+    /** Fingerprint of the instance + package components (and the inherited identity). */
+    etag: string;
+    name: {
+        value: string;
+        from: Origin;
+    };
+    description: {
+        value?: string;
+        from: Origin;
+    };
+    icon: {
+        value?: string;
+        from: Origin;
+    };
+    /**
+     * Configured slots. `key` is the R2 key for instance / fallback slots. A package slot
+     * carries no key (connect-service has no package bytes) but `v`, the package logo's
+     * 16-char content fingerprint.
+     */
+    logos: Partial<Record<LogoType, {
+        from: Origin;
+        key?: string;
+        v?: string;
+    }>>;
+    /** `app:logos.blurhash`, passed through as stored. */
+    blurhash?: {
+        value: unknown;
+        from: Origin;
+    };
+    /**
+     * The passport / brand color (`__blocklet__.js` passportColor, OG gradient). Instance
+     * and fallback values pass through as stored; the package value is `#rrggbb`.
+     */
+    passportColor?: {
+        value: unknown;
+        from: Origin;
+    };
+    /**
+     * The package layer (logo / palette / passportColor) as the host supplied it, carried
+     * SEPARATELY from the resolved fields above. A build-time identity may resolve a field
+     * from the instance (e.g. CF `buildHandler` reads app:branding, so its passportColor
+     * is the instance's); per-request resolution reads the package layer from here, so
+     * clearing the instance value falls back to the package rather than to the default.
+     * Absent when the package supplies none of them.
+     */
+    packageLayer?: PackageLayer;
+    theme: {
+        /** `formatThemeForOutput` of the stored theme (`{}` when none). */
+        value: any;
+        /**
+         * The prefer the stored theme declares — current concept's prefer, else the
+         * top-level prefer — with no default. The login page uses this rule; it differs
+         * from `value.prefer` (which defaults to "system" and ignores the top-level prefer
+         * in the concepts shape) and both are preserved as-is.
+         */
+        prefer?: unknown;
+        from: Origin;
+    };
+}
+export interface PackageLayer {
+    logo?: {
+        v: string;
+    };
+    /** `formatPackageThemeForOutput` of the package palette. */
+    theme?: any;
+    passportColor?: string;
+}
+/** A stored JSON object row, or `{}` for absent / malformed / non-object rows. */
+export declare function parseSettingObject(raw: string | null | undefined): Record<string, any>;
+export declare function resolveAppIdentity(input: AppIdentityInput): AppIdentity;
+/** The legacy `AppInfo` shape (`resolveAppInfo`'s output) of an identity. */
+export declare function toAppInfo(identity: AppIdentity): AppInfo;
+/**
+ * Wrap an `AppInfo` a host resolved on its own (no per-field origins available) as an
+ * identity. Labelled `"deployment"`: it is host/deployment-supplied, and must never
+ * read as instance-configured.
+ */
+export declare function identityFromAppInfo(appInfo: AppInfo): AppIdentity;
+interface SettingReader {
+    getSetting(instanceDid: string, key: string): Promise<string | null>;
+}
+/**
+ * Read the requested identity rows of `instanceDid` (one `getSetting` per field, in
+ * parallel). The caller owns the scope decision — which instance's rows answer this
+ * request — and says so via `scope`.
+ */
+export declare function readInstanceIdentityRows(store: SettingReader, instanceDid: string, fields: readonly IdentityRowField[], scope?: "own" | "fallback"): Promise<InstanceIdentityRows>;
+/**
+ * The requested identity rows out of an already-loaded settings map (e.g. from
+ * `listSettings`). Pass `fields` explicitly: a surface that does not honor a layer
+ * (e.g. legacy `app:name`) must not receive it just because the map happens to hold it.
+ */
+export declare function instanceIdentityRowsFromSettings(settings: ReadonlyMap<string, string | null> | undefined, fields?: readonly IdentityRowField[], scope?: "own" | "fallback"): InstanceIdentityRows;
+/**
+ * The `scope` of rows read from `readInstanceDid`, given the instance the HOST asserted
+ * for this request — the route-context `instanceDid`, or `X-Instance-Did` only on an
+ * embedded host that opted in with `trustInstanceHeader` (the same signal that decides
+ * branding scope; never a raw client header).
+ *
+ *   - nothing asserted (root / control-plane request, single-tenant) → `"own"`
+ *   - asserted X and the rows are X's → `"own"`
+ *   - asserted X but the rows are another scope's (or no scope) → `"fallback"`
+ */
+export declare function identityScopeFor(readInstanceDid: string | undefined, assertedInstanceDid: string | undefined): "own" | "fallback";
+/** The slots a logo type falls back through, most specific first. */
+export declare function logoFallbackChain(type: string): readonly string[];
+/**
+ * The slot that answers `type`: the FIRST configured slot along its fallback chain.
+ * That slot decides — a miss on its bytes serves the generated fallback, it does not
+ * continue down the chain.
+ */
+export declare function resolveLogoSlot(identity: AppIdentity, type: string): {
+    slot: LogoType;
+    from: Origin;
+    key?: string;
+} | null;
+/**
+ * Whether a derived surface (`__blocklet__.js`) advertises `type`'s own URL (did#248).
+ *
+ * On when `type`'s fallback chain resolves to a slot that is either `type` itself
+ * (configured on the instance / fallback scope, or the package's `square`), or the
+ * package logo reached through the chain — arc serves the package bytes on every path
+ * whose chain reaches it (arc#7077). A D1 slot reached only THROUGH the chain does not
+ * turn a variant on: that is today's output for D1-configured apps, locked by the S1
+ * baseline (`logoSquare` combo), and this rule leaves it unchanged. Splash / og-image
+ * chains never reach `square`, so a package-only app leaves them off.
+ */
+export declare function advertisesLogoSlot(identity: AppIdentity, type: string): boolean;
+/**
+ * The 16-char content fingerprint of a resolved logo slot: the R2 key's last segment
+ * truncated to 16 (an instance / fallback upload), else the package logo's `v` (already
+ * 16 chars, arc#7073 red line 4). One length, one lineage — OG cache keys use it.
+ */
+export declare function logoFingerprint(entry: {
+    key?: string;
+    v?: string;
+} | undefined): string | undefined;
+/** `resolveAppInfo`'s historical signature, now a view over {@link resolveAppIdentity}. */
+export declare function resolveAppInfo(params: {
+    brandingRaw: string | null;
+    legacyAppName: string | null;
+    packageBranding?: PackageBranding;
+    deploymentName?: string;
+}): AppInfo;
+export {};
+//# sourceMappingURL=app-identity.d.ts.map

package/dist/app-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-identity.d.ts","sourceRoot":"","sources":["../src/app-identity.ts"],"names":[],"mappings":"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"}