@oxy.so/contracts 1.5.0 → 2.1.0

package/dist/esm/federationInstanceFetch.js

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+import { z } from 'zod';
+/** The longest URL Oxy will sign (the same cap as its own safe fetch). */
+export const INSTANCE_FETCH_MAX_URL_LENGTH = 2048;
+export const instanceFetchSignRequestSchema = z
+    .object({
+    /** The absolute public `https://` URL the caller is about to GET. */
+    url: z.string().trim().min(1).max(INSTANCE_FETCH_MAX_URL_LENGTH),
+})
+    .strict();
+export const instanceFetchSignResponseSchema = z
+    .object({
+    /** The instance actor's key, e.g. `https://oxy.so/ap/users/instance#main-key`. */
+    keyId: z.string().url(),
+    /** Send all three on the GET, as they are. */
+    headers: z
+        .object({
+        Host: z.string().min(1),
+        Date: z.string().min(1),
+        Signature: z.string().min(1),
+    })
+        .strict(),
+})
+    .strict();

package/dist/esm/index.js

@@ -70,7 +70,6 @@ reputationPersonhoodSchema, reputationContributionSchema, reputationConductSchem
 export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
 export { deviceContextRelationshipSchema, deviceDirectoryProfileSchema, deviceAccountContextSchema, devicePrincipalSchema, deviceDirectorySchema, deviceActivateRequestSchema, deviceActivateResponseSchema, deviceDirectorySyncSchema, } from './deviceDirectory.js';
 export { oauthConsentDecisionSchema, oauthAuthorizeCodeResponseSchema, mcpOAuthClientApplicationSchema, mcpOAuthWriteActionSchema, mcpOAuthConsentContextSchema, mcpOAuthClientInfoResponseSchema, mcpOAuthConsentResponseSchema, } from './oauth.js';
-export { BROWSER_HUB_COOKIE_NAME, BROWSER_HUB_COOKIE_ATTRIBUTES, BROWSER_HUB_HANDLE_TTL_MS, browserHubHandleSchema, browserHubHandleRequestSchema, browserHubHandleResponseSchema, browserHubResolveResponseSchema, browserHubErrorSchema, browserHubRevokeResponseSchema, hubSessionSchema, hubClaimRequestSchema, hubActivateRequestSchema, hubAuthorizeRequestSchema, hubAuthorizeResultSchema, } from './browserHub.js';
 export { 
 // Schemas
 loginResultSchema, } from './deviceBoot.js';
@@ -179,4 +178,5 @@ export { emailContextAddressSchema, emailContextMailboxSchema, emailContextMessa
 export { inboxComposeRequestSchema, inboxDailyBriefRequestSchema, inboxNaturalSearchRequestSchema, inboxMessageInferenceParamsSchema, inboxInferenceTextResponseSchema, inboxNaturalSearchResponseSchema, inboxSmartRepliesResponseSchema, inboxThreadSummaryResponseSchema, inboxInferenceStreamEventSchema, } from './inference/inbox.js';
 export * from './externalIdentity.js';
 export * from './linkedAccounts.js';
+export * from './federationInstanceFetch.js';
 export * from './notifications.js';

package/dist/esm/linkedAccounts.js

@@ -88,3 +88,36 @@ export const 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.
+ */
+export const LINKED_ACCOUNT_START_ERROR_REASONS = [
+    'instance_invalid',
+    'instance_unreachable',
+    'handle_unresolvable',
+    'provider_rejected',
+    'provider_unavailable',
+];
+export const linkedAccountStartErrorReasonSchema = z.enum(LINKED_ACCOUNT_START_ERROR_REASONS);
+/** The `details` of a start refusal. */
+export const linkedAccountStartErrorDetailsSchema = z
+    .object({ reason: linkedAccountStartErrorReasonSchema })
+    .strict();

package/dist/esm/notifications.js

@@ -76,3 +76,22 @@ export const createOxyNotificationRequestSchema = 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.
+ */
+export const OXY_ACCOUNT_PUSH_CHANNEL = 'account';
+/** Runtime type discriminator of the push that announces a `system` notification. */
+export const 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.
+ */
+export const oxySystemNotificationPushDataSchema = z.object({
+    type: z.literal(OXY_SYSTEM_NOTIFICATION_PUSH_TYPE),
+    notificationId: z.string().min(1).max(64),
+});