@oxy.so/contracts 2.0.0 → 2.1.0

package/dist/cjs/federationInstanceFetch.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Wire contract for `POST /federation/instance-fetch/sign`: Oxy's INSTANCE
+ * actor signs one ActivityPub GET for a first-party service, so the service can
+ * read an instance running in authorized-fetch ("secure") mode without holding
+ * a key.
+ *
+ * The caller sends a URL, never a signing string: Oxy builds the string itself
+ * (`(request-target): get <path>`, `host`, `date`), the method is always GET
+ * and the key is always the instance actor's. The caller sends the returned
+ * headers, unchanged, on exactly that URL, within the few minutes remote
+ * servers accept a `Date` for. A redirect is a new URL and needs a new
+ * signature.
+ *
+ * Needs a service token whose application holds the privileged
+ * `federation:instance-fetch` scope.
+ *
+ * Platform-agnostic — zod only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instanceFetchSignResponseSchema = exports.instanceFetchSignRequestSchema = exports.INSTANCE_FETCH_MAX_URL_LENGTH = void 0;
+const zod_1 = require("zod");
+/** The longest URL Oxy will sign (the same cap as its own safe fetch). */
+exports.INSTANCE_FETCH_MAX_URL_LENGTH = 2048;
+exports.instanceFetchSignRequestSchema = zod_1.z
+    .object({
+    /** The absolute public `https://` URL the caller is about to GET. */
+    url: zod_1.z.string().trim().min(1).max(exports.INSTANCE_FETCH_MAX_URL_LENGTH),
+})
+    .strict();
+exports.instanceFetchSignResponseSchema = zod_1.z
+    .object({
+    /** The instance actor's key, e.g. `https://oxy.so/ap/users/instance#main-key`. */
+    keyId: zod_1.z.string().url(),
+    /** Send all three on the GET, as they are. */
+    headers: zod_1.z
+        .object({
+        Host: zod_1.z.string().min(1),
+        Date: zod_1.z.string().min(1),
+        Signature: zod_1.z.string().min(1),
+    })
+        .strict(),
+})
+    .strict();

package/dist/cjs/index.js

@@ -683,4 +683,5 @@ Object.defineProperty(exports, "inboxThreadSummaryResponseSchema", { enumerable:
 Object.defineProperty(exports, "inboxInferenceStreamEventSchema", { enumerable: true, get: function () { return inbox_1.inboxInferenceStreamEventSchema; } });
 __exportStar(require("./externalIdentity"), exports);
 __exportStar(require("./linkedAccounts"), exports);
+__exportStar(require("./federationInstanceFetch"), exports);
 __exportStar(require("./notifications"), exports);

package/dist/cjs/linkedAccounts.js

@@ -11,7 +11,7 @@
  * Platform-agnostic — zod only, no react/react-native/expo.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LINKED_ACCOUNT_CALLBACK_ERRORS = exports.serviceLinkedAccountListResponseSchema = exports.serviceLinkedAccountSchema = exports.linkedAccountListResponseSchema = exports.completeLinkedAccountResponseSchema = exports.linkedAccountSchema = exports.completeLinkedAccountRequestSchema = exports.startLinkedAccountResponseSchema = exports.startLinkedAccountRequestSchema = exports.linkedAccountNetworkSchema = exports.LINKED_ACCOUNT_NETWORKS = void 0;
+exports.linkedAccountStartErrorDetailsSchema = exports.linkedAccountStartErrorReasonSchema = exports.LINKED_ACCOUNT_START_ERROR_REASONS = exports.LINKED_ACCOUNT_CALLBACK_ERRORS = exports.serviceLinkedAccountListResponseSchema = exports.serviceLinkedAccountSchema = exports.linkedAccountListResponseSchema = exports.completeLinkedAccountResponseSchema = exports.linkedAccountSchema = exports.completeLinkedAccountRequestSchema = exports.startLinkedAccountResponseSchema = exports.startLinkedAccountRequestSchema = exports.linkedAccountNetworkSchema = exports.LINKED_ACCOUNT_NETWORKS = void 0;
 const zod_1 = require("zod");
 exports.LINKED_ACCOUNT_NETWORKS = ['activitypub', 'atproto'];
 exports.linkedAccountNetworkSchema = zod_1.z.enum(exports.LINKED_ACCOUNT_NETWORKS);
@@ -91,3 +91,36 @@ exports.LINKED_ACCOUNT_CALLBACK_ERRORS = [
     'verification_failed',
     'provider_unavailable',
 ];
+/**
+ * Why `POST /linked-accounts/:network/start` refused, as `details.reason` on
+ * its 400 (`{ error: 'BAD_REQUEST', message, details: { reason } }`). The
+ * message is for logs; show the user a text chosen from the reason.
+ *
+ * - `instance_invalid`: the ActivityPub `instance` is not a server name.
+ * - `instance_unreachable`: the server does not resolve to a public address, or
+ *   could not be connected to.
+ * - `handle_unresolvable`: the atproto handle or DID does not resolve to an
+ *   account. The only reason that means "check what you typed".
+ * - `provider_rejected`: the other network answered and refused Oxy's
+ *   request — for atproto an authorization-server error such as
+ *   `invalid_client_metadata`; for a Mastodon-API server a refused app
+ *   registration (often: not a Mastodon-compatible server). Nothing the user
+ *   typed is wrong.
+ * - `provider_unavailable`: the other network could not be asked right now
+ *   (its OAuth metadata did not load, a 5xx, a timeout). Try again later.
+ *
+ * A refusal with no `details.reason` (a bad `returnTo`, a missing field) is a
+ * client bug, not something to show.
+ */
+exports.LINKED_ACCOUNT_START_ERROR_REASONS = [
+    'instance_invalid',
+    'instance_unreachable',
+    'handle_unresolvable',
+    'provider_rejected',
+    'provider_unavailable',
+];
+exports.linkedAccountStartErrorReasonSchema = zod_1.z.enum(exports.LINKED_ACCOUNT_START_ERROR_REASONS);
+/** The `details` of a start refusal. */
+exports.linkedAccountStartErrorDetailsSchema = zod_1.z
+    .object({ reason: exports.linkedAccountStartErrorReasonSchema })
+    .strict();

package/dist/cjs/notifications.js

@@ -12,7 +12,7 @@
  * Platform-agnostic — zod only, no react/react-native/expo.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOxyNotificationRequestSchema = exports.OXY_NOTIFICATION_URL_MAX = exports.OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX = exports.OXY_SYSTEM_NOTIFICATION_TITLE_MAX = exports.OXY_NOTIFICATION_ENTITY_TYPES = exports.OXY_NOTIFICATION_TYPES = void 0;
+exports.oxySystemNotificationPushDataSchema = exports.OXY_SYSTEM_NOTIFICATION_PUSH_TYPE = exports.OXY_ACCOUNT_PUSH_CHANNEL = exports.createOxyNotificationRequestSchema = exports.OXY_NOTIFICATION_URL_MAX = exports.OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX = exports.OXY_SYSTEM_NOTIFICATION_TITLE_MAX = exports.OXY_NOTIFICATION_ENTITY_TYPES = exports.OXY_NOTIFICATION_TYPES = void 0;
 const zod_1 = require("zod");
 exports.OXY_NOTIFICATION_TYPES = [
     'like',
@@ -79,3 +79,22 @@ exports.createOxyNotificationRequestSchema = zod_1.z
         }
     }
 });
+/**
+ * Android notification channel a `system` notification is pushed on — a wire
+ * contract, because Android 8+ silently drops a push whose channel the app has
+ * not created. Created by the vault (Commons) before it registers its token.
+ */
+exports.OXY_ACCOUNT_PUSH_CHANNEL = 'account';
+/** Runtime type discriminator of the push that announces a `system` notification. */
+exports.OXY_SYSTEM_NOTIFICATION_PUSH_TYPE = 'oxy_system_notification';
+/**
+ * The ONLY data a `system` notification's push carries: its id. The title and
+ * message ride as the push's own title and body; the deep link does NOT travel,
+ * because a push payload is untrusted at the receiver. On a tap the vault
+ * re-reads the notification from Oxy by id (scoped to the signed-in recipient)
+ * and opens the `url` stored there.
+ */
+exports.oxySystemNotificationPushDataSchema = zod_1.z.object({
+    type: zod_1.z.literal(exports.OXY_SYSTEM_NOTIFICATION_PUSH_TYPE),
+    notificationId: zod_1.z.string().min(1).max(64),
+});