@phis/contracts 0.3.1 → 0.4.0

package/dist/media-storage.js

@@ -26,8 +26,17 @@ export const PHI_LOCAL_MEDIA_STORAGE_PROVIDER_ID = "@phis/server/storage-local";
  * therefore carries the algorithm that produced it.
  */
 export const PHIS_MEDIA_CHECKSUM_ALGORITHMS = [
-    "sha256", "sha512", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5",
+    "sha256", "sha512", "sha256-composite", "xxhash128", "crc64nvme", "crc32c", "crc32", "md5",
 ];
+/*
+ * The division and the composite's recorded form live in `./media.ts`, and are re-exported here.
+ *
+ * They are the one part of this contract a browser has to compute as well: the Client hashes the parts
+ * before a plan exists, because a part digest can only be signed into a part request if it is known when
+ * that request is signed. So the rule cannot sit behind the Add-on surface, and it must not be written
+ * twice -- two copies of a division are two divisions the day one of them is edited.
+ */
+export { PHIS_MEDIA_UPLOAD_MAX_PART_COUNT, PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES, formatPhiMediaCompositeChecksum, parsePhiMediaCompositeChecksum, resolvePhiMediaUploadPartCount, resolvePhiMediaUploadPartSizeBytes, } from "./media.js";
 /**
  * The digests strong enough to answer "is this the same file", rather than only "did it arrive intact".
  *
@@ -39,7 +48,20 @@ export const PHIS_MEDIA_CHECKSUM_ALGORITHMS = [
  * substituted file -- so the cost of trusting a weak digest is that someone who may already write to a
  * Space can stop one file from entering it. Small, but not nothing, and free to avoid.
  */
-export const PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS = ["sha256", "sha512"];
+export const PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS = ["sha256", "sha512", "sha256-composite"];
+/**
+ * Why `sha256-composite` is identity-grade although it hashes digests rather than bytes.
+ *
+ * It is `SHA256` over the concatenated part digests of a body divided by a fixed rule. For the question
+ * duplicate detection asks -- are these the same bytes -- it is as hard to forge as SHA-256 itself: a
+ * second file matching one requires a SHA-256 collision in some part. What it cannot do is compare across
+ * divisions, which is why the division is written into the value and why the rule above is frozen.
+ *
+ * It exists because a browser cannot produce the other kind for a large file. Web Crypto has no
+ * incremental digest, so a whole-object SHA-256 means holding the entire body in memory; a part digest is
+ * one part, and the composite over those is a few kilobytes. The choice is not between this and a
+ * whole-object digest, it is between this and no digest at all.
+ */
 export function isPhisMediaIdentityChecksum(algorithm) {
     return PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS.includes(algorithm);
 }
@@ -53,11 +75,17 @@ export function isPhisMediaIdentityChecksum(algorithm) {
  *
  * Only identity-grade digests are eligible. A CRC an endpoint also verifies still proves a transfer
  * intact, and Core records it when that is what arrived; it is simply not what a Profile asks for.
+ *
+ * `sha256-composite` is not eligible either, for a different reason: it is not something an endpoint
+ * verifies, it is the form a SHA-256 takes when a body arrived in parts. A Profile records a base
+ * algorithm, and an object assembled from parts under a `sha256` Profile carries the composite of it.
  */
 export function choosePhisMediaChecksumAlgorithm(probe) {
     if (!probe)
         return null;
     for (const candidate of PHIS_MEDIA_IDENTITY_CHECKSUM_ALGORITHMS) {
+        if (candidate === "sha256-composite")
+            continue;
         if (probe.verifiedAlgorithms.includes(candidate))
             return candidate;
     }

package/dist/media.d.ts

@@ -104,9 +104,9 @@ export type PhiImageAssetVariantSpec = {
     quality: number;
     format: "webp";
 };
-export declare function normalizePhiMediaKind(kind: string | null | undefined): "binary" | "other" | "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font";
-export declare function resolvePhiMediaKindFromContentType(contentType: string | null | undefined): "binary" | "other" | "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font";
-export declare function normalizePhiImageAssetVariantKey(key: unknown): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 9 | 7 | 8 | null;
+export declare function normalizePhiMediaKind(kind: string | null | undefined): "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font" | "binary" | "other";
+export declare function resolvePhiMediaKindFromContentType(contentType: string | null | undefined): "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font" | "binary" | "other";
+export declare function normalizePhiImageAssetVariantKey(key: unknown): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 9 | 8 | null;
 export declare function resolvePhiImageAssetVariantKeyName(key: number | null | undefined): string | null;
 export declare function resolvePhiImageAssetVariantSpec(key: number | null | undefined): PhiImageAssetVariantSpec | null;
 /**
@@ -226,3 +226,47 @@ export declare function isPhiFontSubsetKey(value: unknown): value is PhiFontSubs
  * `LatinExt` where `sr` preloads `Cyrillic`.
  */
 export declare function resolvePhiFontPreloadSubsetKeys(locale: string | null | undefined, coverage: PhiFontCoverage): PhiFontSubsetKeyValue[];
+/**
+ * How a body above one part is divided, as a rule rather than as a Provider's private arithmetic.
+ *
+ * It lives here because two parties have to agree on it and neither can be told by the other in time. The
+ * Provider needs the part size to sign one request per part; the Client needs it *before* the plan exists,
+ * because a digest can only be signed into a request if it is known when the request is signed -- so the
+ * Client has to hash the same divisions the Provider is about to address. A rule both compute from the
+ * byte size is the only arrangement where that holds without an extra round trip.
+ *
+ * **Frozen once objects exist under it.** A `sha256-composite` value is a digest of part digests, so it
+ * answers "the same bytes divided the same way". Change the division and the same file yields a different
+ * value, which splits duplicate detection into cohorts that can never match across the change. The value
+ * carries the part size for exactly this reason: a changed rule produces non-matches, never false matches.
+ * Changing it is therefore a decision about the whole corpus, not a tuning knob.
+ *
+ * `PHIS_MEDIA_UPLOAD_MAX_PART_COUNT` is well under S3's ten thousand on purpose. Every part is signed up
+ * front, so the count is also the size of the plan a Client receives and Core holds in memory.
+ */
+export declare const PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES: number;
+export declare const PHIS_MEDIA_UPLOAD_MAX_PART_COUNT = 1000;
+/**
+ * The part size for one body, and the same answer wherever it is asked.
+ *
+ * Sixteen mebibytes until that would need more parts than are allowed, and from there the smallest whole
+ * mebibyte that fits the body into the allowance. Whole mebibytes keep the number short where it is
+ * recorded and keep the arithmetic exact in a browser, where sizes are doubles.
+ */
+export declare function resolvePhiMediaUploadPartSizeBytes(sizeBytes: number): number;
+/** How many parts one body is divided into under `resolvePhiMediaUploadPartSizeBytes`. */
+export declare function resolvePhiMediaUploadPartCount(sizeBytes: number): number;
+/**
+ * The recorded form of a `sha256-composite` digest: the digest, the part count, the part size.
+ *
+ * Duplicate detection compares these values as strings, so everything that decides whether two of them
+ * mean the same thing has to be inside the string. The digest alone would not: the same bytes divided
+ * differently hash differently, and a value that did not say how it was divided would look like a plain
+ * SHA-256 that simply failed to match. Naming the division makes a mismatch legible instead of puzzling.
+ */
+export declare function formatPhiMediaCompositeChecksum(digestHex: string, partCount: number, partSizeBytes: number): string;
+export declare function parsePhiMediaCompositeChecksum(value: string): {
+    digest: string;
+    partCount: number;
+    partSizeBytes: number;
+} | null;

package/dist/media.js

@@ -360,3 +360,62 @@ export function resolvePhiFontPreloadSubsetKeys(locale, coverage) {
             : PHI_FONT_SUBSET_PRELOAD_BY_LANGUAGE[language] ?? [];
     return [PhiFontSubsetKey.Latin, ...extra].filter((key) => coverage.subsets.includes(key));
 }
+/**
+ * How a body above one part is divided, as a rule rather than as a Provider's private arithmetic.
+ *
+ * It lives here because two parties have to agree on it and neither can be told by the other in time. The
+ * Provider needs the part size to sign one request per part; the Client needs it *before* the plan exists,
+ * because a digest can only be signed into a request if it is known when the request is signed -- so the
+ * Client has to hash the same divisions the Provider is about to address. A rule both compute from the
+ * byte size is the only arrangement where that holds without an extra round trip.
+ *
+ * **Frozen once objects exist under it.** A `sha256-composite` value is a digest of part digests, so it
+ * answers "the same bytes divided the same way". Change the division and the same file yields a different
+ * value, which splits duplicate detection into cohorts that can never match across the change. The value
+ * carries the part size for exactly this reason: a changed rule produces non-matches, never false matches.
+ * Changing it is therefore a decision about the whole corpus, not a tuning knob.
+ *
+ * `PHIS_MEDIA_UPLOAD_MAX_PART_COUNT` is well under S3's ten thousand on purpose. Every part is signed up
+ * front, so the count is also the size of the plan a Client receives and Core holds in memory.
+ */
+export const PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES = 16 * 1024 * 1024;
+export const PHIS_MEDIA_UPLOAD_MAX_PART_COUNT = 1000;
+/**
+ * The part size for one body, and the same answer wherever it is asked.
+ *
+ * Sixteen mebibytes until that would need more parts than are allowed, and from there the smallest whole
+ * mebibyte that fits the body into the allowance. Whole mebibytes keep the number short where it is
+ * recorded and keep the arithmetic exact in a browser, where sizes are doubles.
+ */
+export function resolvePhiMediaUploadPartSizeBytes(sizeBytes) {
+    const mebibyte = 1024 * 1024;
+    if (sizeBytes <= PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES * PHIS_MEDIA_UPLOAD_MAX_PART_COUNT) {
+        return PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES;
+    }
+    return Math.ceil(Math.ceil(sizeBytes / PHIS_MEDIA_UPLOAD_MAX_PART_COUNT) / mebibyte) * mebibyte;
+}
+/** How many parts one body is divided into under `resolvePhiMediaUploadPartSizeBytes`. */
+export function resolvePhiMediaUploadPartCount(sizeBytes) {
+    return Math.max(1, Math.ceil(sizeBytes / resolvePhiMediaUploadPartSizeBytes(sizeBytes)));
+}
+/**
+ * The recorded form of a `sha256-composite` digest: the digest, the part count, the part size.
+ *
+ * Duplicate detection compares these values as strings, so everything that decides whether two of them
+ * mean the same thing has to be inside the string. The digest alone would not: the same bytes divided
+ * differently hash differently, and a value that did not say how it was divided would look like a plain
+ * SHA-256 that simply failed to match. Naming the division makes a mismatch legible instead of puzzling.
+ */
+export function formatPhiMediaCompositeChecksum(digestHex, partCount, partSizeBytes) {
+    return `${digestHex.toLowerCase()}-${partCount}-${partSizeBytes}`;
+}
+export function parsePhiMediaCompositeChecksum(value) {
+    const match = /^([0-9a-f]{64})-(\d{1,5})-(\d{1,12})$/u.exec(value.trim().toLowerCase());
+    if (!match)
+        return null;
+    const partCount = Number(match[2]);
+    const partSizeBytes = Number(match[3]);
+    if (partCount < 1 || partSizeBytes < 1)
+        return null;
+    return { digest: match[1], partCount, partSizeBytes };
+}

package/dist/resource-links.d.ts

@@ -0,0 +1,94 @@
+/**
+ * References from a Phi record to something in another system: `@phis/server/resource-links:v1`.
+ *
+ * A ticket that is also a GitHub issue, a task that is also a pull request, a thread that is also a
+ * conversation somewhere else. The reference is a row of its own rather than a column on the record,
+ * because a record may have several at once, across several systems, and a column per system is a
+ * schema change per integration.
+ *
+ * The provider is the Add-on that wrote the link, and it is the whole of the ownership rule: an Add-on
+ * reads and writes its own links and sees no others. Two integrations pointing at one ticket therefore
+ * do not have to know about each other, and removing one takes its references with it.
+ *
+ * The link is also what an Add-on's actorless access is made of. A person who can see a record writes
+ * the link; from then on the Add-on may read and append to the conversation that record carries, and
+ * nothing beyond it. Unlinking ends that -- which is why `Synced` is stated per link rather than
+ * assumed: a reference that is only a pointer should not become a standing permission.
+ */
+/** What a link points away from. */
+export type PhisResourceLinkSubject = {
+    kind: "thread";
+    id: number;
+} | {
+    kind: "ticket";
+    id: number;
+} | {
+    kind: "ticketTask";
+    id: number;
+};
+/** What is true of a link, as bit flags. */
+export declare const PhisResourceLinkFlag: {
+    /**
+     * The two sides are kept in step, and this Add-on may reach the subject's thread without an actor.
+     *
+     * A link without it is a reference someone recorded: it is shown, it is followed, and it grants
+     * nothing.
+     */
+    readonly Synced: number;
+};
+/**
+ * One reference, as Core stores it.
+ *
+ * `type` and `state` are the provider's own vocabulary -- an issue, a pull request, open, merged -- and
+ * Core never interprets either. It stores them, indexes the external id against them, and hands them
+ * back; what `21` means is the Add-on's business, exactly as a role name is.
+ */
+export type PhisResourceLink = {
+    id: number;
+    subject: PhisResourceLinkSubject;
+    type: number;
+    externalId: string;
+    url: string | null;
+    state: number | null;
+    flags: number;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * The resource links capability: `@phis/server/resource-links:v1`.
+ *
+ * Bounded twice: to this Add-on's own links, and to subjects the acting user may reach. Writing needs
+ * an actor -- a link is a person saying these two things belong together, and it is what later lets the
+ * Add-on act with no person there. A hook or a job may read the links it wrote and may not make new
+ * ones.
+ */
+export type PhisResourceLinksCapabilityV1 = {
+    /** This Add-on's links on one subject, or none where the subject is out of reach. */
+    list(subject: PhisResourceLinkSubject): Promise<PhisResourceLink[]>;
+    /**
+     * Records a reference, or hands back the one that is already there.
+     *
+     * Asking twice is how an id is learned, the way a declared group is: `(type, externalId)` is unique
+     * within this Add-on and this Site, so a second call answers with the first link instead of failing.
+     */
+    link(input: {
+        subject: PhisResourceLinkSubject;
+        type: number;
+        externalId: string;
+        url?: string | null;
+        state?: number | null;
+        flags?: number;
+    }): Promise<PhisResourceLink>;
+    /** Moves a link's provider-local state. */
+    setState(input: {
+        linkId: number;
+        state: number | null;
+    }): Promise<boolean>;
+    /** Removes a link, and with it whatever actorless reach it granted. */
+    unlink(linkId: number): Promise<boolean>;
+    /** One link of this Add-on by the external id it recorded, or null. */
+    findByExternalId(input: {
+        type: number;
+        externalId: string;
+    }): Promise<PhisResourceLink | null>;
+};

package/dist/resource-links.js

@@ -0,0 +1,27 @@
+/**
+ * References from a Phi record to something in another system: `@phis/server/resource-links:v1`.
+ *
+ * A ticket that is also a GitHub issue, a task that is also a pull request, a thread that is also a
+ * conversation somewhere else. The reference is a row of its own rather than a column on the record,
+ * because a record may have several at once, across several systems, and a column per system is a
+ * schema change per integration.
+ *
+ * The provider is the Add-on that wrote the link, and it is the whole of the ownership rule: an Add-on
+ * reads and writes its own links and sees no others. Two integrations pointing at one ticket therefore
+ * do not have to know about each other, and removing one takes its references with it.
+ *
+ * The link is also what an Add-on's actorless access is made of. A person who can see a record writes
+ * the link; from then on the Add-on may read and append to the conversation that record carries, and
+ * nothing beyond it. Unlinking ends that -- which is why `Synced` is stated per link rather than
+ * assumed: a reference that is only a pointer should not become a standing permission.
+ */
+/** What is true of a link, as bit flags. */
+export const PhisResourceLinkFlag = {
+    /**
+     * The two sides are kept in step, and this Add-on may reach the subject's thread without an actor.
+     *
+     * A link without it is a reference someone recorded: it is shown, it is followed, and it grants
+     * nothing.
+     */
+    Synced: 1 << 0,
+};

package/dist/site-groups.d.ts

@@ -36,3 +36,18 @@ export declare const PHI_GROUP_MEMBERSHIP_LEVELS: readonly [1, number, number, n
  * Reading downwards is what makes an unknown higher bit fail closed rather than round up.
  */
 export declare function readPhiGroupMembershipLevel(value: unknown): PhiGroupMembershipFlagValue | null;
+/**
+ * A group a Module needs the Site to have, named rather than created.
+ *
+ * It travels in a Module's `seed` and is written when the Area carrying that Module is published. The
+ * key is the Module's own and never changes: it is what makes a second publish find the group it made
+ * the first time instead of making another. `provider_id` is the Module's id and is supplied by the
+ * materialization, not by the declaration, so a Module cannot claim a group belonging to another.
+ *
+ * The name is a starting value. Once the row exists it is the Site's, and administration renames it
+ * without the next publish undoing that.
+ */
+export type PhisDeclaredSiteGroup = {
+    readonly key: string;
+    readonly name: string;
+};