@sparkvault/sdk-mobile 7.0.1 → 7.0.2

package/dist/app-sdk/upload-publication.d.ts

@@ -12,7 +12,18 @@
  */
 export function uploadTransferReference(istk: string): string;
 /**
- * The upload publication contract between Forge and Core's activation.
+ * Why Core revoked the upload token a forge-transactions record is
+ * (UPLOAD_TOKEN_REVOCATION's reasons), or null for any other record, or none:
+ * the one reading Core's mint and every Forge read of a token apply.
+ *
+ * @param {Object|null|undefined} record - A forge-transactions record, or none
+ * @returns {string|null}
+ */
+export function uploadTokenRevocationReason(record: Object | null | undefined): string | null;
+/**
+ * The upload publication contract between Forge and Core's activation, and
+ * the facts of a transfer token both services spell: its shape, and Core's
+ * revocation of an upload's token.
  *
  * Forge stamps UPLOAD_PUBLICATION_PROTOCOL on every upload session it creates
  * and on the final state it hands Core's activation (POST
@@ -38,6 +49,15 @@ export const UPLOAD_PUBLICATION_PROTOCOL: 2;
  * the session's id.
  */
 export const UPLOAD_ID_PATTERN: RegExp;
+/** The random bytes an ISTK, the bearer token of one Forge transfer, is spelled from. */
+export const ISTK_BYTES: 32;
+/**
+ * An ISTK as Core mints one: the unpadded base64url of its ISTK_BYTES random
+ * bytes, 43 characters. Forge reads a presented token as a forge-transactions
+ * key only in this shape: the table keys other records too (an upload's token
+ * pointer, `UPLOAD_TOKEN#{upload_id}`), which no request may read as a token.
+ */
+export const ISTK_PATTERN: RegExp;
 /**
  * How much of an ISTK names a transfer's charge on the usage ledger: enough to
  * be unique to the token, never the whole bearer credential.
@@ -72,6 +92,37 @@ export const UPLOAD_REFUSAL_CODES: Readonly<{
  * any other a gone session.
  */
 export const UPLOAD_FINAL_REFUSAL_CODES: readonly ("UPLOAD_SUPERSEDED" | "UPLOAD_POOL_FULL")[];
+/**
+ * The words an upload a later staging of its ingot superseded is refused in
+ * (UPLOAD_SUPERSEDED), whichever service meets it: Core's activation, Core's
+ * mint of a token it revoked before issuing it, and Forge meeting a token Core
+ * revoked when the later staging superseded its upload.
+ */
+export const UPLOAD_SUPERSEDED_MESSAGE: "A later upload replaced this one before it finished. The later upload is the one kept, so this one was discarded.";
+/**
+ * Core's revocation of an upload's encrypt token: the `status` it writes on
+ * the token's forge-transactions record, and the `revoked_reason` beside it,
+ * written by the write that ends the upload's staging. Each reason is the
+ * refusal every reader of the token answers the upload with from then on,
+ * as Core's activation refuses such an upload: Core's mint of a token it
+ * revoked before issuing it, and Forge on every request the token, or a
+ * session it opened, makes.
+ *
+ * - UPLOAD_SUPERSEDED: a later staging of its ingot superseded the upload
+ *   (410 UPLOAD_SUPERSEDED, in UPLOAD_SUPERSEDED_MESSAGE's words), which no
+ *   new upload remedies;
+ * - INGOT_DELETED: the ingot it was staged onto was deleted, by a delete or
+ *   the cascade of its folder, vault or account (a 404 naming the ingot, as
+ *   activation answers an upload whose ingot is gone), which ends the upload
+ *   alone: a new upload can store the file again.
+ */
+export const UPLOAD_TOKEN_REVOCATION: Readonly<{
+    status: "revoked";
+    reasons: Readonly<{
+        UPLOAD_SUPERSEDED: "UPLOAD_SUPERSEDED";
+        INGOT_DELETED: "INGOT_DELETED";
+    }>;
+}>;
 /**
  * The response header that names the code Core refused an upload with for
  * good: Forge sends it on every terminal answer to a tus request, a HEAD's

package/dist/app-sdk/upload-publication.js

@@ -2,7 +2,9 @@
 // Source of truth: packages/app-sdk/src/upload-publication.js
 // Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
 /**
- * The upload publication contract between Forge and Core's activation.
+ * The upload publication contract between Forge and Core's activation, and
+ * the facts of a transfer token both services spell: its shape, and Core's
+ * revocation of an upload's token.
  *
  * Forge stamps UPLOAD_PUBLICATION_PROTOCOL on every upload session it creates
  * and on the final state it hands Core's activation (POST
@@ -28,6 +30,15 @@ export const UPLOAD_PUBLICATION_PROTOCOL = 2;
  * the session's id.
  */
 export const UPLOAD_ID_PATTERN = /^tus_[0-9a-f]{32}$/;
+/** The random bytes an ISTK, the bearer token of one Forge transfer, is spelled from. */
+export const ISTK_BYTES = 32;
+/**
+ * An ISTK as Core mints one: the unpadded base64url of its ISTK_BYTES random
+ * bytes, 43 characters. Forge reads a presented token as a forge-transactions
+ * key only in this shape: the table keys other records too (an upload's token
+ * pointer, `UPLOAD_TOKEN#{upload_id}`), which no request may read as a token.
+ */
+export const ISTK_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${Math.ceil((ISTK_BYTES * 4) / 3)}}$`);
 /**
  * How much of an ISTK names a transfer's charge on the usage ledger: enough to
  * be unique to the token, never the whole bearer credential.
@@ -83,6 +94,51 @@ export const UPLOAD_FINAL_REFUSAL_CODES = Object.freeze([
     UPLOAD_REFUSAL_CODES.UPLOAD_POOL_FULL,
     UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED
 ]);
+/**
+ * The words an upload a later staging of its ingot superseded is refused in
+ * (UPLOAD_SUPERSEDED), whichever service meets it: Core's activation, Core's
+ * mint of a token it revoked before issuing it, and Forge meeting a token Core
+ * revoked when the later staging superseded its upload.
+ */
+export const UPLOAD_SUPERSEDED_MESSAGE = 'A later upload replaced this one before it finished. The later upload is the one kept, so this one was discarded.';
+/**
+ * Core's revocation of an upload's encrypt token: the `status` it writes on
+ * the token's forge-transactions record, and the `revoked_reason` beside it,
+ * written by the write that ends the upload's staging. Each reason is the
+ * refusal every reader of the token answers the upload with from then on,
+ * as Core's activation refuses such an upload: Core's mint of a token it
+ * revoked before issuing it, and Forge on every request the token, or a
+ * session it opened, makes.
+ *
+ * - UPLOAD_SUPERSEDED: a later staging of its ingot superseded the upload
+ *   (410 UPLOAD_SUPERSEDED, in UPLOAD_SUPERSEDED_MESSAGE's words), which no
+ *   new upload remedies;
+ * - INGOT_DELETED: the ingot it was staged onto was deleted, by a delete or
+ *   the cascade of its folder, vault or account (a 404 naming the ingot, as
+ *   activation answers an upload whose ingot is gone), which ends the upload
+ *   alone: a new upload can store the file again.
+ */
+export const UPLOAD_TOKEN_REVOCATION = Object.freeze({
+    status: 'revoked',
+    reasons: Object.freeze({
+        UPLOAD_SUPERSEDED: UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED,
+        INGOT_DELETED: 'INGOT_DELETED'
+    })
+});
+const REVOCATION_REASONS = Object.values(UPLOAD_TOKEN_REVOCATION.reasons);
+/**
+ * Why Core revoked the upload token a forge-transactions record is
+ * (UPLOAD_TOKEN_REVOCATION's reasons), or null for any other record, or none:
+ * the one reading Core's mint and every Forge read of a token apply.
+ *
+ * @param {Object|null|undefined} record - A forge-transactions record, or none
+ * @returns {string|null}
+ */
+export function uploadTokenRevocationReason(record) {
+    if (record?.status !== UPLOAD_TOKEN_REVOCATION.status)
+        return null;
+    return REVOCATION_REASONS.includes(record.revoked_reason) ? record.revoked_reason : null;
+}
 /**
  * The response header that names the code Core refused an upload with for
  * good: Forge sends it on every terminal answer to a tus request, a HEAD's

package/dist/app-sdk/upload-publication.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload-publication.js","sourceRoot":"","sources":["../../src/app-sdk/upload-publication.js"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,8DAA8D;AAC9D,8DAA8D;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAI;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,6BAA6B,EAAE,CAAC;QAC5E,MAAM,IAAI,SAAS,CACjB,+EAA+E,6BAA6B,aAAa,CAC1H,CAAC;IACJ,CAAC;IACD,OAAO,+BAA+B,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,wBAAwB,EAAE,0BAA0B;IACpD,uBAAuB,EAAE,yBAAyB;IAClD,iBAAiB,EAAE,mBAAmB;IACtC,gBAAgB,EAAE,kBAAkB;CACrC,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,oBAAoB,CAAC,gBAAgB;IACrC,oBAAoB,CAAC,iBAAiB;CACvC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC"}
+{"version":3,"file":"upload-publication.js","sourceRoot":"","sources":["../../src/app-sdk/upload-publication.js"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,8DAA8D;AAC9D,8DAA8D;AAE9D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAEtD,yFAAyF;AACzF,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9F;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAI;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,6BAA6B,EAAE,CAAC;QAC5E,MAAM,IAAI,SAAS,CACjB,+EAA+E,6BAA6B,aAAa,CAC1H,CAAC;IACJ,CAAC;IACD,OAAO,+BAA+B,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,wBAAwB,EAAE,0BAA0B;IACpD,uBAAuB,EAAE,yBAAyB;IAClD,iBAAiB,EAAE,mBAAmB;IACtC,gBAAgB,EAAE,kBAAkB;CACrC,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,oBAAoB,CAAC,gBAAgB;IACrC,oBAAoB,CAAC,iBAAiB;CACvC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,mHAAmH,CAAC;AAEtH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC;IACnD,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;QACrB,iBAAiB,EAAE,oBAAoB,CAAC,iBAAiB;QACzD,aAAa,EAAE,eAAe;KAC/B,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAM;IAChD,IAAI,MAAM,EAAE,MAAM,KAAK,uBAAuB,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO,kBAAkB,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3F,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkvault/sdk-mobile",
-  "version": "7.0.1",
+  "version": "7.0.2",
   "description": "Mobile SDK for SparkVault Identity, vault, folder, and ingot workflows",
   "type": "module",
   "main": "./dist/index.js",

package/src/app-sdk/upload-publication.js

@@ -3,7 +3,9 @@
 // Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
 
 /**
- * The upload publication contract between Forge and Core's activation.
+ * The upload publication contract between Forge and Core's activation, and
+ * the facts of a transfer token both services spell: its shape, and Core's
+ * revocation of an upload's token.
  *
  * Forge stamps UPLOAD_PUBLICATION_PROTOCOL on every upload session it creates
  * and on the final state it hands Core's activation (POST
@@ -32,6 +34,17 @@ export const UPLOAD_PUBLICATION_PROTOCOL = 2;
  */
 export const UPLOAD_ID_PATTERN = /^tus_[0-9a-f]{32}$/;
 
+/** The random bytes an ISTK, the bearer token of one Forge transfer, is spelled from. */
+export const ISTK_BYTES = 32;
+
+/**
+ * An ISTK as Core mints one: the unpadded base64url of its ISTK_BYTES random
+ * bytes, 43 characters. Forge reads a presented token as a forge-transactions
+ * key only in this shape: the table keys other records too (an upload's token
+ * pointer, `UPLOAD_TOKEN#{upload_id}`), which no request may read as a token.
+ */
+export const ISTK_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${Math.ceil((ISTK_BYTES * 4) / 3)}}$`);
+
 /**
  * How much of an ISTK names a transfer's charge on the usage ledger: enough to
  * be unique to the token, never the whole bearer credential.
@@ -93,6 +106,55 @@ export const UPLOAD_FINAL_REFUSAL_CODES = Object.freeze([
   UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED
 ]);
 
+/**
+ * The words an upload a later staging of its ingot superseded is refused in
+ * (UPLOAD_SUPERSEDED), whichever service meets it: Core's activation, Core's
+ * mint of a token it revoked before issuing it, and Forge meeting a token Core
+ * revoked when the later staging superseded its upload.
+ */
+export const UPLOAD_SUPERSEDED_MESSAGE =
+  'A later upload replaced this one before it finished. The later upload is the one kept, so this one was discarded.';
+
+/**
+ * Core's revocation of an upload's encrypt token: the `status` it writes on
+ * the token's forge-transactions record, and the `revoked_reason` beside it,
+ * written by the write that ends the upload's staging. Each reason is the
+ * refusal every reader of the token answers the upload with from then on,
+ * as Core's activation refuses such an upload: Core's mint of a token it
+ * revoked before issuing it, and Forge on every request the token, or a
+ * session it opened, makes.
+ *
+ * - UPLOAD_SUPERSEDED: a later staging of its ingot superseded the upload
+ *   (410 UPLOAD_SUPERSEDED, in UPLOAD_SUPERSEDED_MESSAGE's words), which no
+ *   new upload remedies;
+ * - INGOT_DELETED: the ingot it was staged onto was deleted, by a delete or
+ *   the cascade of its folder, vault or account (a 404 naming the ingot, as
+ *   activation answers an upload whose ingot is gone), which ends the upload
+ *   alone: a new upload can store the file again.
+ */
+export const UPLOAD_TOKEN_REVOCATION = Object.freeze({
+  status: 'revoked',
+  reasons: Object.freeze({
+    UPLOAD_SUPERSEDED: UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED,
+    INGOT_DELETED: 'INGOT_DELETED'
+  })
+});
+
+const REVOCATION_REASONS = Object.values(UPLOAD_TOKEN_REVOCATION.reasons);
+
+/**
+ * Why Core revoked the upload token a forge-transactions record is
+ * (UPLOAD_TOKEN_REVOCATION's reasons), or null for any other record, or none:
+ * the one reading Core's mint and every Forge read of a token apply.
+ *
+ * @param {Object|null|undefined} record - A forge-transactions record, or none
+ * @returns {string|null}
+ */
+export function uploadTokenRevocationReason(record) {
+  if (record?.status !== UPLOAD_TOKEN_REVOCATION.status) return null;
+  return REVOCATION_REASONS.includes(record.revoked_reason) ? record.revoked_reason : null;
+}
+
 /**
  * The response header that names the code Core refused an upload with for
  * good: Forge sends it on every terminal answer to a tus request, a HEAD's