@oxy.so/core 1.0.0 → 1.1.1

package/src/i18n/locales/es-ES.json

@@ -1412,7 +1412,7 @@
     },
     "details": {
       "cardDetails": "Detalles de la tarjeta",
-      "oxyPay": "Oxy Pay",
+      "peable": "Peable",
       "faircoinPayment": "Pago con FairCoin",
       "paymentDetails": "Detalles del pago",
       "creditCard": "Tarjeta de crédito",
@@ -1438,7 +1438,7 @@
       "amount": "Monto",
       "paymentMethod": "Método de pago",
       "card": "Tarjeta",
-      "oxyPayAccount": "Cuenta Oxy Pay",
+      "peableAccount": "Cuenta Peable",
       "faircoinWallet": "Billetera FairCoin",
       "paidViaQR": "Pagado vía QR",
       "processing": "Procesando...",
@@ -1465,8 +1465,8 @@
         "description": "Paga de forma segura con tu tarjeta de crédito o débito."
       },
       "oxy": {
-        "label": "Oxy Pay",
-        "description": "Usa tu saldo de Oxy Pay en la app."
+        "label": "Peable",
+        "description": "Usa tu saldo de Peable en la app."
       },
       "faircoin": {
         "label": "FAIRWallet",
@@ -2127,6 +2127,18 @@
       "title": "Permisos solicitados",
       "basic": "Iniciar sesión y leer tu perfil básico"
     },
+    "resource": {
+      "title": "App de Oxy y recurso protegido"
+    },
+    "writeActions": {
+      "title": "Acciones que puede realizar esta conexión"
+    },
+    "effects": {
+      "write": "Escritura",
+      "external": "Externa",
+      "financial": "Financiera",
+      "security": "Seguridad"
+    },
     "scopes": {
       "openid": "Confirmar tu identidad",
       "profile": "Leer tu perfil básico",
@@ -2147,7 +2159,8 @@
       "federationWrite": "Actuar en servicios federados"
     },
     "account": {
-      "title": "Iniciando sesión como"
+      "title": "Iniciando sesión como",
+      "id": "ID de cuenta: {{id}}"
     },
     "links": {
       "website": "Sitio web",

package/src/index.ts

@@ -122,8 +122,23 @@ export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type {
     PublicApplication,
     ConnectedApp,
+    ConnectedMcpClient,
 } from './mixins/OxyServices.connectedApps';
 
+// ---------------------------------------------------------------------------
+// Native Alia and digital-agent authority
+// ---------------------------------------------------------------------------
+export type {
+    AccountCapabilityPolicy,
+    AvailableCapabilityCatalog,
+    CapabilityExecutionAuthorization,
+    CreateDelegationGrantInput,
+    DelegationCatalogBinding,
+    DelegationGrantView,
+    PutAccountCapabilityPolicyInput,
+    UpdateDelegationGrantInput,
+} from './mixins/OxyServices.agency';
+
 // ---------------------------------------------------------------------------
 // App store (public storefront + reviews + the listing a publisher edits)
 // ---------------------------------------------------------------------------

package/src/mixins/OxyServices.agency.ts

@@ -0,0 +1,277 @@
+/**
+ * Native Alia and digital-agent authority.
+ *
+ * These methods manage Oxy-owned delegation grants, account autonomy policy,
+ * execution authorizations and their audit trail. They deliberately use the
+ * signed-in account session: capability tickets and app service credentials
+ * stay on the server and are never exposed to Settings clients.
+ */
+import type {
+  AppCapabilityCatalog,
+  AuditEvent,
+  AutonomyLevel,
+  CapabilityCatalogBinding,
+  CapabilityPackage,
+  DelegationGrant,
+  GrantLimit,
+  ResourceRef,
+  ToolGrantOverride,
+} from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { CACHE_TIMES } from './mixinHelpers';
+
+export type DelegationCatalogBinding = CapabilityCatalogBinding;
+export type DelegationGrantView = DelegationGrant;
+
+export interface CreateDelegationGrantInput {
+  ownerAccountId: string;
+  actorAccountId: string;
+  resource: ResourceRef;
+  capabilityPackages: CapabilityPackage[];
+  capabilities: string[];
+  toolOverrides?: ToolGrantOverride[];
+  limits?: GrantLimit[];
+  maximumAutonomy: AutonomyLevel;
+  canRedelegate?: boolean;
+  expiresAt?: string | null;
+}
+
+export type UpdateDelegationGrantInput = Pick<
+  CreateDelegationGrantInput,
+  | 'capabilityPackages'
+  | 'capabilities'
+  | 'toolOverrides'
+  | 'limits'
+  | 'maximumAutonomy'
+  | 'canRedelegate'
+  | 'expiresAt'
+>;
+
+export interface AvailableCapabilityCatalog {
+  id: string;
+  appId: string;
+  version: string;
+  digest: string;
+  audience: string;
+  catalog: AppCapabilityCatalog;
+}
+
+export interface AccountCapabilityPolicy {
+  id: string;
+  accountId: string;
+  appSlug: string;
+  maximumAutonomy: AutonomyLevel;
+  deniedCapabilities: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PutAccountCapabilityPolicyInput {
+  accountId: string;
+  maximumAutonomy: AutonomyLevel;
+  deniedCapabilities: string[];
+}
+
+export interface CapabilityExecutionAuthorization {
+  id: string;
+  kind: 'direct_request' | 'automation';
+  requesterAccountId: string;
+  ownerAccountId: string;
+  coordinatorApplicationId: string;
+  coordinatorCredentialId: string;
+  actorType: 'alia' | 'agent';
+  actorAccountId: string | null;
+  resourceApp: string;
+  effectiveAccountId: string;
+  resourceType: string;
+  resourceKey: string;
+  tool: string;
+  runId: string | null;
+  stepId: string | null;
+  automationId: string | null;
+  maximumAutonomy: AutonomyLevel;
+  limits: GrantLimit[];
+  expiresAt: string;
+  revokedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function query(path: string, key: string, value: string): string {
+  return `${path}?${key}=${encodeURIComponent(value)}`;
+}
+
+export function OxyServicesAgencyMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    async listAvailableCapabilityCatalogs(accountId: string): Promise<AvailableCapabilityCatalog[]> {
+      try {
+        const response = await this.makeRequest<{ catalogs: AvailableCapabilityCatalog[] }>(
+          'GET',
+          query('/capabilities/catalogs/available', 'accountId', accountId),
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return response.catalogs;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async listDelegationGrants(ownerAccountId: string): Promise<DelegationGrantView[]> {
+      try {
+        const response = await this.makeRequest<{ grants: DelegationGrantView[] }>(
+          'GET',
+          query('/capabilities/grants', 'ownerAccountId', ownerAccountId),
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return response.grants;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async createDelegationGrant(input: CreateDelegationGrantInput): Promise<DelegationGrantView> {
+      try {
+        const response = await this.makeRequest<{ grant: DelegationGrantView }>(
+          'POST',
+          '/capabilities/grants',
+          input,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(input.ownerAccountId)}`);
+        return response.grant;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async revokeDelegationGrant(grantId: string, ownerAccountId: string): Promise<void> {
+      try {
+        await this.makeRequest<void>(
+          'DELETE',
+          `/capabilities/grants/${encodeURIComponent(grantId)}`,
+          undefined,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async updateDelegationGrant(
+      grantId: string,
+      ownerAccountId: string,
+      input: UpdateDelegationGrantInput,
+    ): Promise<DelegationGrantView> {
+      try {
+        const response = await this.makeRequest<{ grant: DelegationGrantView }>(
+          'PUT',
+          `/capabilities/grants/${encodeURIComponent(grantId)}`,
+          input,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
+        return response.grant;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async listAccountCapabilityPolicies(accountId: string): Promise<AccountCapabilityPolicy[]> {
+      try {
+        const response = await this.makeRequest<{ policies: AccountCapabilityPolicy[] }>(
+          'GET',
+          query('/capabilities/account-policies', 'accountId', accountId),
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return response.policies;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async putAccountCapabilityPolicy(
+      appId: string,
+      input: PutAccountCapabilityPolicyInput,
+    ): Promise<AccountCapabilityPolicy> {
+      try {
+        const response = await this.makeRequest<{ policy: AccountCapabilityPolicy }>(
+          'PUT',
+          `/capabilities/account-policies/${encodeURIComponent(appId)}`,
+          input,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/capabilities/account-policies?accountId=${encodeURIComponent(input.accountId)}`);
+        return response.policy;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async deleteAccountCapabilityPolicy(appId: string, accountId: string): Promise<void> {
+      try {
+        await this.makeRequest<void>(
+          'DELETE',
+          `/capabilities/account-policies/${encodeURIComponent(appId)}?accountId=${encodeURIComponent(accountId)}`,
+          undefined,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/capabilities/account-policies?accountId=${encodeURIComponent(accountId)}`);
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async listCapabilityExecutionAuthorizations(
+      ownerAccountId: string,
+    ): Promise<CapabilityExecutionAuthorization[]> {
+      try {
+        const response = await this.makeRequest<{ authorizations: CapabilityExecutionAuthorization[] }>(
+          'GET',
+          query('/capabilities/execution-authorizations', 'ownerAccountId', ownerAccountId),
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return response.authorizations;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async revokeCapabilityExecutionAuthorization(
+      authorizationId: string,
+      ownerAccountId: string,
+    ): Promise<void> {
+      try {
+        await this.makeRequest<void>(
+          'DELETE',
+          `/capabilities/execution-authorizations/${encodeURIComponent(authorizationId)}`,
+          undefined,
+          { cache: false },
+        );
+        this.clearCacheEntry(
+          `GET:/capabilities/execution-authorizations?ownerAccountId=${encodeURIComponent(ownerAccountId)}`,
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    async listCapabilityAuditEvents(accountId: string): Promise<AuditEvent[]> {
+      try {
+        const response = await this.makeRequest<{ events: AuditEvent[] }>(
+          'GET',
+          query('/capabilities/audit', 'accountId', accountId),
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return response.events;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.assets.ts

@@ -1,8 +1,8 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceLinkedDownloadUrl } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxy.so/protocol';
 import { logger } from '../logger';
-import { AssetUrlResolutionError, ServiceAssetMetadataError } from '../OxyServices.errors';
+import { AssetUrlResolutionError, ServiceAssetMetadataError, ServiceLinkedDownloadUrlError } from '../OxyServices.errors';
 import { extractErrorStatus } from '../utils/errorUtils';
 import { redactUrlQuery } from '../utils/redactUrl';
 
@@ -22,6 +22,14 @@ const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
  */
 const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
 
+/**
+ * Maximum number of ids sent per `POST /assets/service/linked-url` request.
+ * Matches that route's own cap, which is a QUARTER of the metadata routes' —
+ * see `MAX_ASSETS_LINKED_URL` in the API for why minting download credentials is
+ * budgeted more tightly than projecting rows.
+ */
+const SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE = 25;
+
 /**
  * Lowercase hex SHA-256 digest matcher (exactly 64 hex chars). The reverse
  * lookup drops non-conforming hashes client-side so a single malformed value
@@ -426,6 +434,101 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       return settled.flat();
     }
 
+    /**
+     * Mint short-lived direct download URLs for files the calling application's
+     * own users attached to it, via `POST /assets/service/linked-url`.
+     *
+     * This is the ONLY path in this SDK by which a service token reaches file
+     * BYTES. {@link getServiceAssetMetadataByIds} is metadata-only, and every
+     * other download helper here — {@link getFileDownloadUrl},
+     * {@link getFileDownloadUrlAsync}, {@link getBatchFileAccess} — resolves a URL
+     * for the CURRENT USER through `makeRequest`, which is a different question: a
+     * relying service holds no user session, and the buyer whose entitlement it is
+     * enforcing is not a viewer Oxy knows anything about.
+     *
+     * **Service-token auth (required), plus the `files:linked:read` scope**, which
+     * is NOT implied by `files:read`. The calling client must be service-configured
+     * (`configureServiceAuth(apiKey, apiSecret)`); a user-session request is
+     * rejected by the route's service-auth guard.
+     *
+     * **What the server will and will not give you.** A URL comes back only for a
+     * file whose OWN OWNER linked it to this application (`file_links.created_by =
+     * files.owner_user_id`). Every other id is omitted: unknown, deleted,
+     * system-owned, linked by somebody else, or not linked here at all. So the
+     * result is routinely shorter than the input and must be mapped by `id`.
+     *
+     * ABSENCE IS A REFUSAL, NOT A FACT ABOUT THE FILE, and the caller is the only
+     * party that can tell the difference. The route deliberately cannot — it
+     * answers identically for "no such file" and "not yours" so it leaks nothing —
+     * which means a service must decide what to tell its user from its OWN
+     * entitlement record, never from this response. Do not surface "file not
+     * found" on the strength of an omission.
+     *
+     * FAILURE IS NOT ABSENCE EITHER, and here it cannot be opted out of: a failed
+     * chunk throws {@link ServiceLinkedDownloadUrlError} carrying its ids, with no
+     * `{ partial: true }` mode. Swallowing a 429 would tell a user who paid for a
+     * file that it is not there. An empty input resolves to `[]` with no network
+     * call.
+     *
+     * Never cached at the SDK layer, and that is a stronger statement than the
+     * sibling methods' "low hit rate": each entry is a live credential for the
+     * bytes, so caching one keeps it usable after the service has decided the
+     * caller's entitlement ended.
+     */
+    async getServiceLinkedDownloadUrls(ids: string[]): Promise<ServiceLinkedDownloadUrl[]> {
+      const uniqueIds = Array.from(
+        new Set(ids.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)),
+      );
+      if (uniqueIds.length === 0) {
+        return [];
+      }
+
+      const chunks: string[][] = [];
+      for (let i = 0; i < uniqueIds.length; i += SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE) {
+        chunks.push(uniqueIds.slice(i, i + SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE));
+      }
+
+      // Chunks stay independent so one failure never cancels work already in
+      // flight; the failures are collected and re-raised together below, exactly
+      // as in the metadata sibling.
+      const unresolvedIds: string[] = [];
+      const statuses: number[] = [];
+      let firstError: unknown;
+
+      const settled = await Promise.all(
+        chunks.map(async (chunk): Promise<ServiceLinkedDownloadUrl[]> => {
+          try {
+            const entries = await this.makeServiceRequest<ServiceLinkedDownloadUrl[]>(
+              'POST',
+              '/assets/service/linked-url',
+              { ids: chunk },
+            );
+            return Array.isArray(entries) ? entries : [];
+          } catch (error: unknown) {
+            const status = extractErrorStatus(error);
+            // `chunkSize` and `status`, never the ids and never a `url`: a minted
+            // URL in a log line is a credential in a log line.
+            logger.warn('getServiceLinkedDownloadUrls: chunk failed', {
+              method: 'getServiceLinkedDownloadUrls',
+              chunkSize: chunk.length,
+              status,
+              error: error instanceof Error ? error.message : String(error),
+            });
+            unresolvedIds.push(...chunk);
+            if (typeof status === 'number') statuses.push(status);
+            firstError ??= error;
+            return [];
+          }
+        }),
+      );
+
+      if (unresolvedIds.length > 0) {
+        throw new ServiceLinkedDownloadUrlError(unresolvedIds, statuses, firstError);
+      }
+
+      return settled.flat();
+    }
+
     /**
      * Reverse content-address lookup: resolve many content `sha256` digests to
      * the servable Oxy asset holding each, in one round-trip per chunk via

package/src/mixins/OxyServices.connectedApps.ts

@@ -83,12 +83,20 @@ export interface ConnectedApp {
   lastUsedAt: string;
 }
 
+/** An external MCP client authorized for one exact app resource and account. */
+export interface ConnectedMcpClient {
+  id: string;
+  appSlug: string;
+  resource: string;
+  scopes: string[];
+  clientId: string;
+  clientName: string;
+  createdAt: string;
+  lastUsedAt: string;
+}
+
 export function OxyServicesConnectedAppsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
     /**
      * Resolve an OAuth client identifier to the owning application's PUBLIC
      * identity. No authentication required — the API returns only sanitized,
@@ -170,5 +178,35 @@ export function OxyServicesConnectedAppsMixin<T extends typeof OxyServicesBase>(
         throw this.handleError(error);
       }
     }
+
+    /** List resource-bound external MCP connections for the active Oxy account. */
+    async listConnectedMcpClients(): Promise<ConnectedMcpClient[]> {
+      try {
+        const response = await this.makeRequest<{ grants: ConnectedMcpClient[] }>(
+          'GET',
+          '/auth/mcp/oauth/grants',
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return response.grants;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Revoke one external MCP connection and every token in its family. */
+    async revokeConnectedMcpClient(grantId: string): Promise<void> {
+      try {
+        await this.makeRequest<void>(
+          'DELETE',
+          `/auth/mcp/oauth/grants/${encodeURIComponent(grantId)}`,
+          undefined,
+          { cache: false },
+        );
+        this.clearCacheEntry('GET:/auth/mcp/oauth/grants');
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }

package/src/mixins/OxyServices.utility.ts

@@ -1,12 +1,10 @@
 /**
  * Utility Methods Mixin
  *
- * Provides utility methods including link metadata fetching
- * and Express.js authentication middleware
+ * Provides utility methods including Express.js authentication middleware.
  */
 import { jwtDecode } from 'jwt-decode';
 import type { JsonWebKey } from 'node:crypto';
-import type { LinkPreview } from '@oxy.so/contracts';
 import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadNodeCrypto } from '@oxy.so/protocol';
@@ -278,29 +276,6 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
-    /**
-     * Fetch link metadata
-     */
-    async fetchLinkMetadata(url: string): Promise<{
-      url: string;
-      title: string;
-      description: string;
-      image?: string;
-    }> {
-      try {
-        const path = buildUrl('/links/preview', { url, wait: 1 });
-        const preview = await this.makeRequest<LinkPreview>('GET', path, undefined, { cache: false });
-        return {
-          url: preview.url,
-          title: preview.title?.trim() || preview.url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
-          description: preview.description?.trim() || 'Link',
-          image: preview.image,
-        };
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
     /**
      * Express.js authentication middleware
      *