@mieweb/pulsevault 0.3.0 → 0.4.1

package/protocol/schemas/beat-manifest.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/beat-manifest.schema.json",
+  "title": "Beat manifest",
+  "description": "The `kind: project` artifact (e.g. `<draftId>-beats.pulse`) related to a pulse's video (PROTOCOL.md §8). A beat is a timestamp range inside the video: where one recorded clip starts and ends. Beats are contiguous and sum to `durationMs`.",
+  "type": "object",
+  "required": ["version", "type", "durationMs", "beats"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Manifest format version."
+    },
+    "type": {
+      "type": "string",
+      "const": "beat-manifest",
+      "description": "Identifies the document."
+    },
+    "durationMs": {
+      "type": "number",
+      "minimum": 0,
+      "description": "True duration of the video, in milliseconds."
+    },
+    "beats": {
+      "type": "array",
+      "description": "One entry per recorded clip, in play order.",
+      "items": {
+        "type": "object",
+        "required": ["segmentId", "order", "startMs", "endMs"],
+        "properties": {
+          "segmentId": {
+            "type": "string",
+            "description": "The recorded clip's local id on the capturing device."
+          },
+          "order": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "0-based position of the clip in the video."
+          },
+          "startMs": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Where the clip starts in the video, in milliseconds."
+          },
+          "endMs": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Where the clip ends; equals the next beat's `startMs`."
+          }
+        }
+      }
+    }
+  }
+}

package/protocol/schemas/capabilities.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/capabilities.schema.json",
+  "title": "GET /capabilities response",
+  "description": "Unauthenticated discovery (PROTOCOL.md §2). A client reads it before pairing and pairs only if its protocol range overlaps [minSupportedVersion, maxSupportedVersion]. Clients must ignore fields they don't recognize.",
+  "type": "object",
+  "required": [
+    "protocolVersion",
+    "protocolRevision",
+    "minSupportedVersion",
+    "maxSupportedVersion",
+    "kinds",
+    "allowedExtensions",
+    "maxUploadSize",
+    "checksum"
+  ],
+  "properties": {
+    "protocolVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Protocol major this server implements. Also sent as the `Protocol-Version` header on every response."
+    },
+    "protocolRevision": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$",
+      "description": "Spec revision this server implements, `major.minor`. The minor counts additions older clients can ignore."
+    },
+    "minSupportedVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Oldest protocol major this server accepts. Clients whose newest protocol is older get 426 Upgrade Required."
+    },
+    "maxSupportedVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Newest protocol major this server accepts."
+    },
+    "kinds": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["video", "project", "captions", "thumbnail"] },
+      "description": "Artifact kinds this server accepts."
+    },
+    "allowedExtensions": {
+      "type": "object",
+      "additionalProperties": { "type": "array", "items": { "type": "string" } },
+      "description": "Allowed file extensions per kind, lowercase with the leading dot."
+    },
+    "maxUploadSize": {
+      "type": "number",
+      "description": "Largest artifact the server accepts, in bytes."
+    },
+    "checksum": {
+      "type": "object",
+      "required": ["algorithms"],
+      "properties": {
+        "algorithms": { "type": "array", "items": { "type": "string" } }
+      },
+      "description": "Checksum algorithms accepted in `Upload-Metadata.checksum`."
+    },
+    "viewLinks": {
+      "type": "boolean",
+      "description": "Whether `POST {prefix}/artifacts/<id>/view-link` mints read-only view links (§6.4). Absent before protocol 2.2, which a client treats as false."
+    }
+  }
+}

package/protocol/schemas/capability-token.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/capability-token.schema.json",
+  "title": "Capability token claims",
+  "description": "The claims inside a capability token (PROTOCOL.md §5.4). The token is `base64url(JSON claims).signature`, HMAC-signed by the issuing deployment. It authorizes the artifact it names and any artifact whose `relatedTo` is that artifact.",
+  "type": "object",
+  "required": ["artifactId", "iat", "exp", "kid", "issuer"],
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The artifact the token is for (the pulse's video)."
+    },
+    "iat": {
+      "type": "integer",
+      "description": "Issued at, in seconds since the Unix epoch."
+    },
+    "exp": {
+      "type": "integer",
+      "description": "Expires at, in seconds since the Unix epoch."
+    },
+    "kid": {
+      "type": "string",
+      "description": "Id of the signing key, so a deployment can rotate secrets."
+    },
+    "issuer": {
+      "type": "string",
+      "description": "The issuing deployment. A token from another issuer is rejected."
+    },
+    "use": {
+      "type": "string",
+      "enum": ["view"],
+      "description": "`view` on a read-only view token (§5.5), which only opens artifacts and is signed with a key derived from the secret. Absent on the capability token an upload uses."
+    }
+  }
+}

package/protocol/schemas/deep-link.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/deep-link.schema.json",
+  "title": "Pairing link query parameters",
+  "description": "The query parameters of a `pulsecam://?…` pairing link (PROTOCOL.md §3), as built by `buildUploadLink`. Clients must ignore parameters they don't recognize.",
+  "type": "object",
+  "required": ["v", "artifactId", "server"],
+  "properties": {
+    "v": {
+      "type": "string",
+      "const": "1",
+      "description": "Link format version. A client refuses a link whose `v` it doesn't know."
+    },
+    "artifactId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The artifact the pairing is for: the video's id. Related artifacts declare it as `relatedTo`."
+    },
+    "server": {
+      "type": "string",
+      "format": "uri",
+      "description": "Base URL of the server, including its path prefix (e.g. `https://vault.example.org/pulsevault`). The client builds every request as `${server}/<path>`."
+    },
+    "token": {
+      "type": "string",
+      "description": "Optional credential the client sends as `Authorization: Bearer`. Typically a capability token (capability-token.schema.json)."
+    }
+  }
+}

package/protocol/schemas/pulse-client.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/pulse-client.schema.json",
+  "title": "Pulse-Client request header",
+  "description": "Since 2.1. Optional header a client sends on every request to say what it is and which protocol majors it speaks (PROTOCOL.md §7), e.g. `Pulse/2.1.0 (45; ios); protocol=1-2`. A server answers 426 Upgrade Required on uploads and artifacts when the client's newest protocol is older than its oldest. Without the header, nothing changes.",
+  "type": "string",
+  "pattern": "^[^;]+(;.*)?;\\s*protocol=[0-9]+(-[0-9]+)?\\s*$"
+}

package/protocol/schemas/upload-metadata.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/upload-metadata.schema.json",
+  "title": "TUS Upload-Metadata keys",
+  "description": "The decoded `Upload-Metadata` keys a client sends when it creates an upload (PROTOCOL.md §4). Values are strings, base64-encoded on the wire. Servers ignore keys they don't recognize.",
+  "type": "object",
+  "required": ["artifactId", "filename"],
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The artifact's id. For the video it's the pairing link's `artifactId`; related artifacts use a fresh UUID. Legacy aliases `videoid` and `projectid` are still accepted."
+    },
+    "filename": {
+      "type": "string",
+      "description": "Original file name. Its extension must be allowed for `kind` (see `/capabilities`)."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["video", "project", "captions", "thumbnail"],
+      "default": "video",
+      "description": "Artifact kind. Defaults to `video`."
+    },
+    "relatedTo": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The artifact this one belongs to: the video, for its captions, beat manifest and thumbnail. A capability token for the video also authorizes artifacts related to it."
+    },
+    "checksum": {
+      "type": "string",
+      "pattern": "^(sha256|sha1|md5):[0-9a-fA-F]+$",
+      "description": "`<algorithm>:<hex digest>` of the finished file, verified by servers that check checksums."
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Display title (the draft name), sent on the video. Display-only; servers trim and cap it."
+    },
+    "appVersion": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "Since 2.1. Version of the app that uploaded it, e.g. `2.1.0 (45)`. Stored with the artifact. Display-only; servers trim and cap it."
+    }
+  }
+}

package/protocol/schemas/view-link.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/view-link.schema.json",
+  "title": "POST /artifacts/<id>/view-link response",
+  "description": "A read-only view link to a finished artifact (PROTOCOL.md §6.4, protocol 2.2). The token opens the artifact, and the artifacts `relatedTo` it, as `GET {prefix}/artifacts/<id>?token=<token>` — nothing more, so it is safe to share. The server decides how long it works.",
+  "type": "object",
+  "required": [
+    "token",
+    "expiresAt"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "token": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The view token. Opaque to clients."
+    },
+    "expiresAt": {
+      "type": "integer",
+      "description": "When the link stops working, in seconds since the Unix epoch."
+    }
+  }
+}