feat: HTTP to UCAN bridge

stacks/upload-api-stack.js

@@ -122,6 +122,7 @@ export function UploadApiStack({ stack, app }) {
     routes: {
       'POST /':       'functions/ucan-invocation-router.handler',
       'POST /ucan':   'functions/ucan.handler',
+      'POST /bridge': 'functions/bridge.handler',
       'GET /':        'functions/get.home',
       'GET /validate-email': 'functions/validate-email.preValidateEmail',
       'POST /validate-email': 'functions/validate-email.validateEmail',

upload-api/BRIDGE.md

@@ -0,0 +1,66 @@
+# HTTP-UCAN Bridge
+
+## Summary
+
+We have implemented a "bridge" that allows w3up users to interact with the service
+without implementing the UCAN invocation wire protocols. 
+
+A user can submit an HTTP request like (simplified for clarity):
+
+```
+POST /bridge
+X-Auth-Secret: NGY2YTQ1YjYwNWFiYWU2YWNmYmY4NWFhODc4YjEwYzQ=
+Authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsInVjdiI6IjAuOS4xIn0.eyJhdHQiOlt7ImNhbiI6InVwbG9hZC9saXN0Iiwid2l0aCI6ImRpZDprZXk6ejZNa3JUblpIRU1aQnYzMjRIMlV5N2N1cjZIR29weXRuZkc4V3RBbzEyTFByQjk0In1dLCJhdWQiOiJkaWQ6a2V5Ono2TWtyczNVbkRZVndVZ2FDWDl5OGdVeGY0c2VKblFxSGE5OWltQkhLa2hiekV5dSIsImV4cCI6MTcwNzUyMzIzNCwiaXNzIjoiZGlkOmtleTp6Nk1ralJ4QmkycDdHelRrTFFRSE5RNGZIY1ExWHQzaVBKVVpxRGVKMnd3UTRlVVUiLCJwcmYiOlsiYmFmeXJlaWQ2dXNwNnZncmprNjRuNXZ6ZGlkZ2gyeW9mbHA0NnRwcmZvdnFwdHozM283eTRvcmxyM3EiXX0.VH09YeLZjT28QpipB4kDRHWdnHq08GiwjlCIaxD2z8XXr5-WC2eR39scKYC8_kAxiRc5EdJ8Vj25hwld2eTyBw
+Content-Type: application/json
+
+{
+  "call": "store/add",
+  "on": "did:key:z6Mkm5qHN9g9NQSGbBfL7iGp9sexdssioT4CzyVap9ATqGqX",
+  "inputs": {
+    "link": "bafybeicxsrpxilwb6bdtq6iztjziosrqts5qq2kgali3xuwgwjjjpx5j24",
+    "size": 42
+  }
+}
+```
+
+And receive a JSON-encoded UCAN receipt in response.
+
+### Authorization
+
+The `X-Auth-Secret` and `Authorization` header values can be generated with the `bridge generate-tokens` command of `w3cli`:
+
+```sh
+$ w3 bridge generate-tokens did:key:z6Mkm5qHN9g9NQSGbBfL7iGp9sexdssioT4CzyVap9ATqGqX --expiration 1707264563641
+
+X-Auth-Secret header: NGY2YTQ1YjYwNWFiYWU2YWNmYmY4NWFhODc4YjEwYzQ=
+
+Authorization header: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsInVjdiI6IjAuOS4xIn0.eyJhdHQiOlt7ImNhbiI6InVwbG9hZC9saXN0Iiwid2l0aCI6ImRpZDprZXk6ejZNa3JUblpIRU1aQnYzMjRIMlV5N2N1cjZIR29weXRuZkc4V3RBbzEyTFByQjk0In1dLCJhdWQiOiJkaWQ6a2V5Ono2TWtyczNVbkRZVndVZ2FDWDl5OGdVeGY0c2VKblFxSGE5OWltQkhLa2hiekV5dSIsImV4cCI6MTcwNzUyMzIzNCwiaXNzIjoiZGlkOmtleTp6Nk1ralJ4QmkycDdHelRrTFFRSE5RNGZIY1ExWHQzaVBKVVpxRGVKMnd3UTRlVVUiLCJwcmYiOlsiYmFmeXJlaWQ2dXNwNnZncmprNjRuNXZ6ZGlkZ2gyeW9mbHA0NnRwcmZvdnFwdHozM283eTRvcmxyM3EiXX0.VH09YeLZjT28QpipB4kDRHWdnHq08GiwjlCIaxD2z8XXr5-WC2eR39scKYC8_kAxiRc5EdJ8Vj25hwld2eTyBw
+```
+
+`X-Auth-Secret` is a base64pad-encoded Uint8Array of arbitrary length that will be used to derive an ed25519 principal as follows:
+
+```typescript
+
+import { sha256 } from '@ucanto/core'
+import { ed25519 } from '@ucanto/principal'
+
+async function deriveSigner(secret: Uint8Array): Promise<ed25519.EdSigner> {
+  const { digest } = await sha256.digest(secret)
+  return ed25519.Signer.derive(digest)
+}
+```
+
+`Authorization` is a JWT [Bearer token](https://datatracker.ietf.org/doc/html/rfc6750) representing a UCAN delegation as described by 
+the [`ucan-http-bearer-token`](https:// github.com/ucan-wg/ucan-http-bearer-token?tab=readme-ov-file#ucan-as-bearer-token-specification-v030) specification.
+It should grant the principal identified by `X-Auth-Secret` appropriate capabilities
+on the resource identified in the JSON body of the HTTP request.
+
+### Invocation Fields
+
+`call`, `on` and `inputs` should be specified according to the capability you wish to invoke. 
+
+`call` should be an "ability" string like `store/add` or `upload/add` and must be included in the set of abilities passed to the `--can` option of `w3 bridge generate-tokens`. By default, `--can` is set to `['upload/add', 'store/add']`.
+
+Information about possible `inputs` for a particular ability can be found in https://github.com/web3-storage/specs/
+
+`on` MUST match the resource passed as the first option to `w3 bridge generate-tokens`.

upload-api/functions/bridge.js

@@ -0,0 +1,156 @@
+import * as Sentry from '@sentry/serverless'
+import { invoke, DID } from '@ucanto/core'
+import { connect } from '@ucanto/client'
+import * as CAR from '@ucanto/transport/car'
+import * as HTTP from '@ucanto/transport/http'
+import { sha256 } from '@ucanto/core'
+import { ed25519 } from '@ucanto/principal'
+import { base64pad } from 'multiformats/bases/base64'
+import * as UCAN from "@ipld/dag-ucan"
+
+Sentry.AWSLambda.init({
+  environment: process.env.SST_STAGE,
+  dsn: process.env.SENTRY_DSN,
+  tracesSampleRate: 1.0,
+})
+
+/**
+ * 
+ * @param {Uint8Array} secret
+ * @returns 
+ */
+async function deriveSigner(secret) {
+  const { digest } = await sha256.digest(secret)
+  return await ed25519.Signer.derive(digest)
+}
+
+/**
+ * AWS HTTP Gateway handler for POST / with ucan invocation router.
+ *
+ * We provide responses in Payload format v2.0
+ * see: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.proxy-format
+ *
+ * @param {import('aws-lambda').APIGatewayProxyEventV2} request
+ */
+async function handlerFn(request) {
+  try {
+    const { UPLOAD_API_DID, ACCESS_SERVICE_URL } = process.env
+
+    if (!UPLOAD_API_DID) {
+      return {
+        statusCode: 500,
+        body: 'UPLOAD_API_DID is not set'
+      }
+    }
+
+    if (!ACCESS_SERVICE_URL) {
+      return {
+        statusCode: 500,
+        body: 'ACCESS_SERVICE_URL is not set'
+      }
+    }
+
+    // parse headers
+    const authSecretHeader = request.headers['x-auth-secret']
+    if (!authSecretHeader) {
+      return {
+        statusCode: 401,
+        body: 'request has no x-auth-secret header'
+      }
+    }
+    const secret = base64pad.baseDecode(authSecretHeader)
+
+    const authorizationHeader = request.headers['authorization']
+    if (!authorizationHeader) {
+      return {
+        statusCode: 401,
+        body: 'request has no authorization header'
+      }
+    }
+    if (!authorizationHeader.startsWith('Bearer ')) {
+      return {
+        statusCode: 401,
+        body: 'authorization header must use the Bearer directive'
+      }
+    }
+    const jwt = authorizationHeader.replace('Bearer ', '')
+    const delegation = UCAN.parse(jwt)
+
+    // parse body
+    const body = request.body
+    if (!body) {
+      return {
+        statusCode: 400,
+        body: 'request has no body'
+      }
+    }
+
+    const jsonBody = JSON.parse(body)
+
+    if (
+      (typeof jsonBody.call !== 'string') ||
+      (jsonBody.call.split('/').length < 2)
+    ) {
+      return {
+        statusCode: 400,
+        body: 'call must be /-separated string like "store/add" or "admin/store/info"'
+      }
+    }
+    const ability = /** @type {import('@ucanto/interface').Ability} */(jsonBody.call)
+
+    if (
+      (typeof jsonBody.on !== 'string') ||
+      (jsonBody.on.split(':').length < 2)
+    ) {
+      return {
+        statusCode: 400,
+        body: 'on must be a URI'
+      }
+    }
+    const resource = /** @type {import('@ucanto/interface').Resource} */(jsonBody.on)
+
+    const invocation = invoke({
+      issuer: await deriveSigner(secret),
+      audience: DID.parse(UPLOAD_API_DID),
+      capability: {
+        can: ability,
+        with: resource,
+        nb: jsonBody.inputs
+      },
+      proofs: [delegation]
+    })
+    const receipt = await invocation.execute(connect({
+      id: DID.parse(UPLOAD_API_DID),
+      codec: CAR.outbound,
+      channel: HTTP.open({
+        url: new URL(ACCESS_SERVICE_URL),
+        method: 'POST'
+      })
+    }))
+    const result = receipt.out
+    if (result.ok) {
+      return {
+        statusCode: 200,
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(result.ok)
+      }
+    } else {
+      return {
+        statusCode: 500,
+        body: Buffer.from(result.error?.message ?? 'no error message received').toString('base64'),
+        isBase64Encoded: true
+      }
+    }
+  } catch (/** @type {any} */ error) {
+    console.error(error)
+    return {
+      statusCode: error.status ?? 500,
+      body: Buffer.from(error.message).toString('base64'),
+      isBase64Encoded: true,
+    }
+  }
+}
+
+export const handler = Sentry.AWSLambda.wrapHandler(handlerFn)