doc manual

manual/acp/cmd_auth.md

@@ -0,0 +1,72 @@
+# Policy Command Authentication
+
+In SourceHub, a Policy is defined alongside a set of relationships, which are used to derive authorization decisions for the Policy.
+Relationships in a Policy are mutate (created, deleted or updated) through a Policy Command.
+The command is created and sent by the Policy end users (actors) directly (as opposed to an administrator as is often the case in Access Control systems).
+
+In order to execute these commands, it's necessary to authenticate the entity sending them.
+As it is the end user crafting said commands, actor authentication may be completely isolated from SourceHub and Tx authentcation. 
+
+Currently, there are 3 supported authentication schemes for Policy Commands: direct, signed command and Bearer.
+
+## Direct
+TODO
+
+## Signed
+TODO
+
+## Bearer
+
+Bearer Authentication is done through a JWS.
+A JWS is a signed JSON object containing "claims", which contain data identifying the user.
+
+ACP Bearer JWSs are different from commonly used JWS in that they are self signed (as opposed to generated by party A and used by party B).
+The JWS MUST contain the following claims: `iss`, `exp`, `iat` and `authorized_account`, each claim will be detailed further on.
+All the aforementioned claims MUST be present in the JWS.
+
+### Claims
+
+The `exp` (expires) and `isa` (issued at) claims are used as defined in the JWT RFC, an Unix time stamp (ie seconds since the epoch).
+
+The `iss` claim is as defined by the JWT RFC, it identifies the entity that issued the JWS through a string.
+This string MUST be the DID of the Actor issuing the JWS.
+The DID MUST resolve to a DID Document containing a Verification Method which is a Public Key.
+This public key is used to validate the JWS signature.
+
+The `authorized_account` claim MUST contain a valid SourceHub address (ie a bech32 encoded string with the `source` prefix).
+The address specified in this claim is used to limit which account can use the Bearer JWS.
+A Policy Cmd is only accepted and processed if it is submitted in a Tx signed by the SAME account as the one set in the claim.
+This is done to prevent mallicious actors from extracting Bearer JWSs from the public ledger and impersonating an Actor.
+
+The following is an example of a acceptable Bearer JWS payload:
+```json
+ {
+    "iss": "did:key:z6MkkHsQbp3tXECqmUJoCJwyuxSKn1BDF1RHzwDGg9tHbXKw",
+    "authorized_account": "source12frvft2an4sjrdlvjhjunq9m7j0ygaev05crmh",
+    "iat": 1718814750,
+    "exp": 1718815650
+}
+```
+
+### JWS Signature and Serialization and Headers
+
+The JWS MUST be signed by a private key whose public key is resolvable through the did specified in the `iss` claim.
+
+The signed JWS MUST be serialized using the compact serialization format.
+Bearer JWSs serialized following the JSON Serialization format will be rejected.
+
+All JOSE Header specified in the Bearer JWS are ignored (eg `jku`, `jwk`, `kid`, `x5u`).
+The key used during validation is the one resolved from the issuer did.
+
+The following is an example of a valid Bearer JWS:
+
+```
+eyJhbGciOiJFZERTQSJ9.eyJpc3MiOiJkaWQ6a2V5Ono2TWtrSHNRYnAzdFhFQ3FtVUpvQ0p3eXV4U0tuMUJERjFSSHp3REdnOXRIYlhLdyIsImF1dGhvcml6ZWRfYWNjb3VudCI6InNvdXJjZTEyZnJ2ZnQyYW40c2pyZGx2amhqdW5xOW03ajB5Z2FldjA1Y3JtaCIsImlhdCI6MTcxODgxNDc1MCwiZXhwIjoxNzE4ODE1NjUwfQ.ZW0CLlDU2431FQrqNXxX-lI8aNnjTYPclj-QJVCc8Pqqs3vwqVxKPDSss9dTEcqLCrLxhlGr5kuIFblrhy8NDg
+```
+
+### Notes for SourceHub developers
+
+The Bearer JWS uses the standard timestamping mechanisms defined in JWT (`iat` and `exp`) to ease user adoption.
+Note however that under no circumstance the validation must rely under the local time of the machine running sourcehub.
+The `Block Time` (available through the sdk ctx) MUST be used as the reference time in the system.
+Due to clock skew, this is necessary to maintain the deterministic execution of the blockchain.

manual/acp/readme.md

@@ -0,0 +1 @@
+# ACP Module Manual

manual/readme.md

@@ -0,0 +1 @@
+# SourceHub Manual