snapshot of https://github.com/ory/keto.git (master, 2026-09-16; blobs > 131072B omitted)

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/cli.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -euo pipefail
+
+export KETO_WRITE_REMOTE="127.0.0.1:4467"
+
+echo '// ownership
+directories:/photos#owner@maureen
+files:/photos/beach.jpg#owner@maureen
+files:/photos/mountains.jpg#owner@laura
+
+// maureen granted access to /photos to laura
+directories:/photos#access@laura
+
+// the following tuples are defined implicitly through subject set rewrites (not supported yet)
+directories:/photos#access@(directories:/photos#owner)
+files:/photos/beach.jpg#access@(files:/photos/beach.jpg#owner)
+files:/photos/beach.jpg#access@(directories:/photos#access)
+files:/photos/mountains.jpg#access@(files:/photos/mountains.jpg#owner)
+files:/photos/mountains.jpg#access@(directories:/photos#access)' | \
+  keto relation-tuple parse -f - --format json | \
+    keto relation-tuple create -f - --insecure-disable-transport-security >/dev/null \
+    && echo "Successfully created tuples" \
+    || echo "Encountered error"

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/curl.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -euo pipefail
+
+echo '// ownership
+directories:/photos#owner@maureen
+files:/photos/beach.jpg#owner@maureen
+files:/photos/mountains.jpg#owner@laura
+
+// maureen granted access to /photos to laura
+directories:/photos#access@laura
+
+// the following tuples are defined implicitly through subject set rewrites (not supported yet)
+directories:/photos#access@(directories:/photos#owner)
+files:/photos/beach.jpg#access@(files:/photos/beach.jpg#owner)
+files:/photos/beach.jpg#access@(directories:/photos#access)
+files:/photos/mountains.jpg#access@(files:/photos/mountains.jpg#owner)
+files:/photos/mountains.jpg#access@(directories:/photos#access)' | \
+  keto relation-tuple parse -f - --format json | \
+    jq "[ .[] | { relation_tuple: . , action: \"insert\" } ]" -c | \
+      curl -X PATCH --silent --fail \
+        -H 'Content-Type: application/json' \
+        --retry 7 --retry-connrefused \
+        --data @- \
+        http://127.0.0.1:4467/admin/relation-tuples
+
+echo "Successfully created tuples"

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/expected_output.txt

@@ -0,0 +1 @@
+Successfully created tuples

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/index.js

@@ -0,0 +1,92 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+import grpc from "@ory/keto-grpc-client/node_modules/@grpc/grpc-js/build/src/index.js"
+import { relationTuples, write, writeService } from "@ory/keto-grpc-client"
+
+const writeClient = new writeService.WriteServiceClient(
+  "127.0.0.1:4467",
+  grpc.credentials.createInsecure(),
+)
+
+const writeRequest = new write.TransactRelationTuplesRequest()
+
+const insert = (tuple) => {
+  const tupleDelta = new write.RelationTupleDelta()
+  tupleDelta.setAction(write.RelationTupleDelta.Action.ACTION_INSERT)
+  tupleDelta.setRelationTuple(tuple)
+
+  writeRequest.addRelationTupleDeltas(tupleDelta)
+}
+
+const addSimpleTuple = (namespace, object, relation, user) => {
+  const relationTuple = new relationTuples.RelationTuple()
+  relationTuple.setNamespace(namespace)
+  relationTuple.setObject(object)
+  relationTuple.setRelation(relation)
+
+  const sub = new relationTuples.Subject()
+  sub.setId(user)
+  relationTuple.setSubject(sub)
+
+  insert(relationTuple)
+}
+
+// ownership
+addSimpleTuple("directories", "/photos", "owner", "maureen")
+addSimpleTuple("files", "/photos/beach.jpg", "owner", "maureen")
+addSimpleTuple("files", "/photos/mountains.jpg", "owner", "laura")
+// granted access
+addSimpleTuple("directories", "/photos", "access", "laura")
+
+// should be subject set rewrite
+// owners have access
+;[
+  ["files", "/photos/beach.jpg"],
+  ["files", "/photos/mountains.jpg"],
+  ["directories", "/photos"],
+].forEach(([namespace, object]) => {
+  const relationTuple = new relationTuples.RelationTuple()
+  relationTuple.setNamespace(namespace)
+  relationTuple.setObject(object)
+  relationTuple.setRelation("access")
+
+  const subjectSet = new relationTuples.SubjectSet()
+  subjectSet.setNamespace(namespace)
+  subjectSet.setObject(object)
+  subjectSet.setRelation("owner")
+
+  const sub = new relationTuples.Subject()
+  sub.setSet(subjectSet)
+  relationTuple.setSubject(sub)
+
+  insert(relationTuple)
+})
+
+// should be subject set rewrite
+// access on parent means access on child
+;["/photos/beach.jpg", "/photos/mountains.jpg"].forEach((file) => {
+  const relationTuple = new relationTuples.RelationTuple()
+  relationTuple.setNamespace("files")
+  relationTuple.setObject(file)
+  relationTuple.setRelation("access")
+
+  const subjectSet = new relationTuples.SubjectSet()
+  subjectSet.setNamespace("directories")
+  subjectSet.setObject("/photos")
+  subjectSet.setRelation("access")
+
+  const sub = new relationTuples.Subject()
+  sub.setSet(subjectSet)
+  relationTuple.setSubject(sub)
+
+  insert(relationTuple)
+})
+
+writeClient.transactRelationTuples(writeRequest, (error) => {
+  if (error) {
+    console.log("Encountered error", error)
+  } else {
+    console.log("Successfully created tuples")
+  }
+})

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/main.go

@@ -0,0 +1,95 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"context"
+	"fmt"
+
+	rts "github.com/ory/keto/gen/go/ory/keto/relation_tuples/v1alpha2"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+)
+
+func main() {
+	conn, err := grpc.NewClient("127.0.0.1:4467", grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		panic("Encountered error: " + err.Error())
+	}
+
+	client := rts.NewWriteServiceClient(conn)
+
+	//directories:/photos#owner@maureen
+	//files:/photos/beach.jpg#owner@maureen
+	//files:/photos/mountains.jpg#owner@laura
+	//directories:/photos#access@laura
+	//directories:/photos#access@(directories:/photos#owner)
+	//files:/photos/beach.jpg#access@(files:/photos/beach.jpg#owner)
+	//files:/photos/beach.jpg#access@(directories:/photos#access)
+	//files:/photos/mountains.jpg#access@(files:/photos/mountains.jpg#owner)
+	//files:/photos/mountains.jpg#access@(directories:/photos#access)
+
+	tuples := []*rts.RelationTuple{
+		// ownership
+		{
+			Namespace: "directories",
+			Object:    "/photos",
+			Relation:  "owner",
+			Subject:   rts.NewSubjectID("maureen"),
+		},
+		{
+			Namespace: "files",
+			Object:    "/photos/beach.jpg",
+			Relation:  "owner",
+			Subject:   rts.NewSubjectID("maureen"),
+		},
+		{
+			Namespace: "files",
+			Object:    "/photos/mountains.jpg",
+			Relation:  "owner",
+			Subject:   rts.NewSubjectID("laura"),
+		},
+		// granted access
+		{
+			Namespace: "directories",
+			Object:    "/photos",
+			Relation:  "access",
+			Subject:   rts.NewSubjectID("laura"),
+		},
+	}
+	// should be subject set rewrite
+	// owners have access
+	for _, o := range []struct{ n, o string }{
+		{"files", "/photos/beach.jpg"},
+		{"files", "/photos/mountains.jpg"},
+		{"directories", "/photos"},
+	} {
+		tuples = append(tuples, &rts.RelationTuple{
+			Namespace: o.n,
+			Object:    o.o,
+			Relation:  "access",
+			Subject:   rts.NewSubjectSet(o.n, o.o, "owner"),
+		})
+	}
+	// should be subject set rewrite
+	// access on parent means access on child
+	for _, obj := range []string{"/photos/beach.jpg", "/photos/mountains.jpg"} {
+		tuples = append(tuples, &rts.RelationTuple{
+			Namespace: "files",
+			Object:    obj,
+			Relation:  "access",
+			Subject:   rts.NewSubjectSet("directories", "/photos", "access"),
+		})
+	}
+
+	_, err = client.TransactRelationTuples(context.Background(), &rts.TransactRelationTuplesRequest{
+		RelationTupleDeltas: rts.RelationTupleToDeltas(tuples, rts.RelationTupleDelta_ACTION_INSERT),
+	})
+	if err != nil {
+		panic("Encountered error: " + err.Error())
+	}
+
+	fmt.Println("Successfully created tuples")
+}

contrib/docs-code-samples/expand-api-display-access/01-expand-beach/cli.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -euo pipefail
+
+export KETO_READ_REMOTE="127.0.0.1:4466"
+
+keto expand access files:/photos/beach.jpg --format json-pretty --max-depth 3 --insecure-disable-transport-security

contrib/docs-code-samples/expand-api-display-access/01-expand-beach/curl.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -euo pipefail
+
+curl -G --silent \
+     --retry 7 --retry-connrefused \
+     --data-urlencode "namespace=files" \
+     --data-urlencode "relation=access" \
+     --data-urlencode "object=/photos/beach.jpg" \
+     --data-urlencode "max-depth=3" \
+     http://127.0.0.1:4466/relation-tuples/expand | \
+  jq

contrib/docs-code-samples/expand-api-display-access/01-expand-beach/expected_output.json

@@ -0,0 +1,76 @@
+{
+  "children": [
+    {
+      "children": [
+        {
+          "tuple": {
+            "namespace": "",
+            "object": "",
+            "relation": "",
+            "subject_id": "maureen"
+          },
+          "type": "leaf"
+        }
+      ],
+      "tuple": {
+        "namespace": "",
+        "object": "",
+        "relation": "",
+        "subject_set": {
+          "namespace": "files",
+          "object": "/photos/beach.jpg",
+          "relation": "owner"
+        }
+      },
+      "type": "union"
+    },
+    {
+      "children": [
+        {
+          "tuple": {
+            "namespace": "",
+            "object": "",
+            "relation": "",
+            "subject_id": "laura"
+          },
+          "type": "leaf"
+        },
+        {
+          "tuple": {
+            "namespace": "",
+            "object": "",
+            "relation": "",
+            "subject_set": {
+              "namespace": "directories",
+              "object": "/photos",
+              "relation": "owner"
+            }
+          },
+          "type": "leaf"
+        }
+      ],
+      "tuple": {
+        "namespace": "",
+        "object": "",
+        "relation": "",
+        "subject_set": {
+          "namespace": "directories",
+          "object": "/photos",
+          "relation": "access"
+        }
+      },
+      "type": "union"
+    }
+  ],
+  "tuple": {
+    "namespace": "",
+    "object": "",
+    "relation": "",
+    "subject_set": {
+      "namespace": "files",
+      "object": "/photos/beach.jpg",
+      "relation": "access"
+    }
+  },
+  "type": "union"
+}

contrib/docs-code-samples/expand-api-display-access/01-expand-beach/index.js

@@ -0,0 +1,71 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+import grpc from "@ory/keto-grpc-client/node_modules/@grpc/grpc-js/build/src/index.js"
+import { relationTuples, expand, expandService } from "@ory/keto-grpc-client"
+
+const expandClient = new expandService.ExpandServiceClient(
+  "127.0.0.1:4466",
+  grpc.credentials.createInsecure(),
+)
+
+const subjectSet = new relationTuples.SubjectSet()
+subjectSet.setNamespace("files")
+subjectSet.setRelation("access")
+subjectSet.setObject("/photos/beach.jpg")
+
+const sub = new relationTuples.Subject()
+sub.setSet(subjectSet)
+
+const expandRequest = new expand.ExpandRequest()
+expandRequest.setSubject(sub)
+expandRequest.setMaxDepth(3)
+
+// helper to get a nice result
+const subjectJSON = (subject) => {
+  if (subject.hasId()) {
+    return { subject_id: subject.getId() }
+  }
+  const set = subject.getSet()
+  return {
+    subject_set: {
+      namespace: set.getNamespace(),
+      object: set.getObject(),
+      relation: set.getRelation(),
+    },
+  }
+}
+
+// helper to get a nice result
+const prettyTree = (tree) => {
+  const [nodeType, tuple, children] = [
+    tree.getNodeType(),
+    {
+      tuple: {
+        namespace: "",
+        object: "",
+        relation: "",
+        ...subjectJSON(tree.getSubject()),
+      },
+    },
+    tree.getChildrenList(),
+  ]
+  switch (nodeType) {
+    case expand.NodeType.NODE_TYPE_LEAF:
+      return { type: "leaf", ...tuple }
+    case expand.NodeType.NODE_TYPE_UNION: {
+      const mapped = children.map(prettyTree)
+      return mapped.length > 0
+        ? { type: "union", children: mapped, ...tuple }
+        : { type: "union", ...tuple }
+    }
+  }
+}
+
+expandClient.expand(expandRequest, (error, resp) => {
+  if (error) {
+    console.log("Encountered error:", error)
+  } else {
+    console.log(JSON.stringify(prettyTree(resp.getTree()), null, 2))
+  }
+})

contrib/docs-code-samples/expand-api-display-access/01-expand-beach/main.go

@@ -0,0 +1,41 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+
+	rts "github.com/ory/keto/gen/go/ory/keto/relation_tuples/v1alpha2"
+	"github.com/ory/keto/ketoapi"
+)
+
+func main() {
+	conn, err := grpc.NewClient("127.0.0.1:4466", grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		panic(err)
+	}
+
+	client := rts.NewExpandServiceClient(conn)
+
+	res, err := client.Expand(context.Background(), &rts.ExpandRequest{
+		Subject:  rts.NewSubjectSet("files", "/photos/beach.jpg", "access"),
+		MaxDepth: 3,
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	tree := ketoapi.TreeFromProto[*ketoapi.RelationTuple](res.Tree)
+
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(tree); err != nil {
+		panic(err.Error())
+	}
+}

contrib/docs-code-samples/expand-api-display-access/99-cleanup/cli.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -euo pipefail
+
+export KETO_READ_REMOTE="127.0.0.1:4466"
+export KETO_WRITE_REMOTE="127.0.0.1:4467"
+
+keto relation-tuple get --namespace files --format json --insecure-disable-transport-security | \
+  jq ".relation_tuples" | \
+    keto relation-tuple delete --insecure-disable-transport-security -f - -q > /dev/null
+
+keto relation-tuple get --namespace directories --format json --insecure-disable-transport-security | \
+  jq ".relation_tuples" | \
+    keto relation-tuple delete --insecure-disable-transport-security -f - -q > /dev/null

contrib/docs-code-samples/expand-api-display-access/99-cleanup/curl.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+set -euo pipefail
+
+export KETO_READ_REMOTE="127.0.0.1:4466"
+export KETO_WRITE_REMOTE="127.0.0.1:4467"
+
+curl -G --silent \
+     --retry 7 --retry-connrefused \
+     --data-urlencode "namespace=files" \
+     http://127.0.0.1:4466/relation-tuples | \
+  jq "[ .relation_tuples[] | { relation_tuple: . , action: \"delete\" } ]" -c | \
+    curl -X PATCH --silent --fail \
+      -H 'Content-Type: application/json' \
+      --retry 7 --retry-connrefused \
+      --data @- \
+      http://127.0.0.1:4467/admin/relation-tuples
+
+curl -G --silent \
+     --retry 7 --retry-connrefused \
+     --data-urlencode "namespace=directories" \
+     http://127.0.0.1:4466/relation-tuples | \
+  jq "[ .relation_tuples[] | { relation_tuple: . , action: \"delete\" } ]" -c | \
+    curl -X PATCH --silent --fail \
+      -H 'Content-Type: application/json' \
+      --retry 7 --retry-connrefused \
+      --data @- \
+      http://127.0.0.1:4467/admin/relation-tuples

contrib/docs-code-samples/expand-api-display-access/99-cleanup/index.js

@@ -0,0 +1,23 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+import grpc from "@ory/keto-grpc-client/node_modules/@grpc/grpc-js/build/src/index.js"
+import { relationTuples, write, writeService } from "@ory/keto-grpc-client"
+
+const purgeNamespace = (namespace) => {
+  const query = new relationTuples.RelationQuery()
+  query.setNamespace(namespace)
+  const request = new write.DeleteRelationTuplesRequest()
+  request.setRelationQuery(query)
+  new writeService.WriteServiceClient(
+    "127.0.0.1:4467",
+    grpc.credentials.createInsecure(),
+  ).deleteRelationTuples(request, (err) => {
+    if (err) {
+      console.error(err)
+    }
+  })
+}
+
+purgeNamespace("files")
+purgeNamespace("directories")

contrib/docs-code-samples/expand-api-display-access/99-cleanup/main.go

@@ -0,0 +1,62 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build docscodesamples
+// +build docscodesamples
+
+package main
+
+import (
+	"context"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/protobuf/proto"
+
+	rts "github.com/ory/keto/gen/go/ory/keto/relation_tuples/v1alpha2"
+)
+
+func purgeNamespace(nspace string) {
+	rc, err := grpc.NewClient("127.0.0.1:4466", grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		panic(err)
+	}
+	defer rc.Close()
+
+	rClient := rts.NewReadServiceClient(rc)
+	resp, err := rClient.ListRelationTuples(context.Background(), &rts.ListRelationTuplesRequest{
+		Query: &rts.ListRelationTuplesRequest_Query{
+			Namespace: nspace,
+		},
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	wc, err := grpc.NewClient("127.0.0.1:4467", grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		panic(err)
+	}
+	defer wc.Close()
+
+	deltas := make([]*rts.RelationTupleDelta, len(resp.RelationTuples))
+	for i, rt := range resp.RelationTuples {
+		deltas[i] = &rts.RelationTupleDelta{
+			Action:        rts.RelationTupleDelta_ACTION_DELETE,
+			RelationTuple: proto.Clone(rt).(*rts.RelationTuple),
+		}
+	}
+
+	wClient := rts.NewWriteServiceClient(wc)
+	_, err = wClient.TransactRelationTuples(context.Background(), &rts.TransactRelationTuplesRequest{
+		RelationTupleDeltas: deltas,
+	})
+	if err != nil {
+		panic(err)
+	}
+}
+
+func main() {
+	purgeNamespace("directories")
+	purgeNamespace("files")
+}

contrib/docs-code-samples/expand-api-display-access/keto.yml

@@ -0,0 +1,9 @@
+dsn: memory
+log:
+  level: trace
+
+namespaces:
+  - name: files
+    id: 1
+  - name: directories
+    id: 2